Self-Hosting
Deploy CorvidAgent to your own infrastructure — Docker, systemd, or bare metal.
Deployment Options
Docker
Multi-stage build with Compose. Named volume for SQLite persistence. Production-ready.
systemd
Linux service unit with auto-restart. Install via the included daemon script.
macOS LaunchAgent
Persistent background service on macOS. Starts on login, restarts on crash.
Reverse Proxy
Caddy or nginx configs for TLS termination, WebSocket proxying, and rate limiting.
Docker
Start with Docker Compose
$ git clone https://github.com/CorvidLabs/corvid-agent.git
$ cd corvid-agent
$ cp .env.example .env
# Edit .env with your API keys
$ docker compose -f deploy/docker-compose.yml up -dBuilds a multi-stage image (Angular client in stage 1, production server in stage 2). Database persists via a named db-data volume at /app/data.
Pass Environment Variables
$ export ANTHROPIC_API_KEY=sk-ant-...
$ export API_KEY=your-secret-key
$ export LOG_LEVEL=info
$ docker compose -f deploy/docker-compose.yml up -dThe Compose file forwards key variables. You can also set them in your .env file.
Verify Image Signatures
# Verify image signature (Cosign keyless via Sigstore)
$ cosign verify \
--certificate-identity-regexp "https://github.com/CorvidLabs/corvid-agent" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
ghcr.io/corvidlabs/corvid-agent:latest
# Verify SBOM attestation
$ cosign verify-attestation --type spdxjson \
--certificate-identity-regexp "https://github.com/CorvidLabs/corvid-agent" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
ghcr.io/corvidlabs/corvid-agent:latest | jq -r '.payload' | base64 -d | jq .Released images are signed with Cosign (keyless, via Sigstore/Fulcio) and include an SPDX SBOM attestation.
Localnet Docker Networking
# If Algorand localnet runs on the host machine:
LOCALNET_ALGOD_URL=http://host.docker.internal:4001
LOCALNET_KMD_URL=http://host.docker.internal:4002
LOCALNET_INDEXER_URL=http://host.docker.internal:8980The Compose file includes extra_hosts: ["host.docker.internal:host-gateway"] for Linux compatibility.
systemd
Install the Service
# Install and enable the systemd service
$ ./deploy/daemon.sh install
# Check status
$ systemctl status corvid-agent
# View logs
$ journalctl -u corvid-agent -fThe service unit is at deploy/corvid-agent.service. It runs as a dedicated user with auto-restart on failure.
macOS LaunchAgent
Install the LaunchAgent
# Copy the plist to LaunchAgents
$ cp deploy/com.corvidlabs.corvid-agent.plist ~/Library/LaunchAgents/
# Load and start
$ launchctl load ~/Library/LaunchAgents/com.corvidlabs.corvid-agent.plist
# Check status
$ launchctl list | grep corvidStarts on login and restarts on crash. Edit the plist to adjust the working directory and environment variables for your setup.
Reverse Proxy
When BIND_HOST=0.0.0.0, always place the server behind a reverse proxy with TLS. Configs are in the deploy/ directory.
Caddy
corvid.example.com {
reverse_proxy localhost:3000
}Automatic HTTPS via Let’s Encrypt. Config at deploy/caddy/.
nginx
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}WebSocket upgrade headers are required for real-time streaming. Config at deploy/nginx/.
Environment Variables
Core Server
AI Providers
Multi-Tenant & Backups
Rate Limiting
Auth-tier multipliers: public ×0.5, user ×1, admin ×2. Health and WebSocket endpoints are exempt.
Monitoring
Health Endpoints
# Liveness probe (is the process running?)
$ curl http://localhost:3000/health/live
# Readiness probe (ready for requests?)
$ curl http://localhost:3000/health/readyBoth return HTTP 200 when healthy. Docker healthcheck uses /health/live every 30s. No authentication required.
Logging
Use LOG_FORMAT=json in production for structured log aggregation.
Self-Test Suite
$ curl -X POST http://localhost:3000/api/selftest/run \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"scope": "all"}'Scopes: unit, e2e, all. Verifies server health, database integrity, and agent connectivity.
Database Backups
Create a Backup
# Trigger backup (requires ADMIN_API_KEY)
$ curl -X POST http://localhost:3000/api/backup \
-H "Authorization: Bearer $ADMIN_API_KEY"
# Schedule with cron (every 6 hours)
0 */6 * * * curl -s -X POST http://localhost:3000/api/backup \
-H "Authorization: Bearer $ADMIN_API_KEY" >> /var/log/corvid-backup.log 2>&1Performs a WAL checkpoint before copying. Old backups beyond BACKUP_MAX_KEEP are pruned automatically.
Restore from Backup
# Stop the server first
# Replace the database
$ cp backups/corvid-agent-2026-02-28T12-00-00-000Z.db corvid-agent.db
# Remove stale WAL/SHM files
$ rm -f corvid-agent.db-wal corvid-agent.db-shm
# Restart the server
$ bun run startUpgrading
Bare Metal
$ git pull origin main
$ bun install
$ bun run build:client
$ bun run startMigrations run automatically on startup.
Docker
$ docker compose -f deploy/docker-compose.yml build
$ docker compose -f deploy/docker-compose.yml up -dAlways create a backup before upgrading.