Self-Hosting 53 pages
On this page

Self-Hosting

Production checklist

What to check before exposing a self-hosted Cyborg relay to your team.

The step-by-step setup is in Docker (cloud relay), the supported way to run a relay. The variables are in Configuration.

Before you go live

  • TLS. Put the relay behind a reverse proxy or load balancer that terminates TLS. Machines and browsers should never reach it in the clear.
  • RELAY_PUBLIC_URL. Set it to the https:// origin people will type, with no trailing slash. It is compiled into the web UI, so changing it means docker compose build again.
  • Secrets. Generate them (tools/gen-selfhost-secrets.sh deploy/.env) instead of inventing them: CYBORG7_JWT_SECRET (32+ characters), CYBORG7_DAEMON_TOKEN_SECRET and CYBORG7_REFRESH_TOKEN_SECRET. The generator also writes CYBORG7_TOKEN_ENC_KEY, which a production relay needs in order to boot; keep it with your other secrets; a lost key makes stored integration credentials unreadable.
  • Email. Set RESEND_API_KEY and EMAIL_FROM so sign-up one-time codes can be delivered.
  • Database. Use a managed or otherwise secured PostgreSQL. If its certificate should be verified, set PG_SSL_MODE=verify-full; if it speaks no TLS, set PG_SSL_MODE=disable. Never commit DATABASE_URL.
  • Asset storage. Choose a backend with ASSETS_BACKEND (s3 by default, or fs). With fs, the asset directory must be writable by the container’s unprivileged user.
  • Valkey (Redis-protocol compatible). Optional for a single relay. REDIS_URL carries pub/sub fan-out between relay instances. Rate limits are shared across relays only with REDIS_URL AND a key wrapper, WORKSPACE_KMS_KEY_ID or WORKSPACE_KEK: the shared budgets are keyed by a digest under the fleet key, never by an email or IP. So REDIS_URL requires one of them: a relay with REDIS_URL and neither key wrapper refuses to start (exit 78), and the deploy precheck refuses the restart first. tools/gen-selfhost-secrets.sh writes WORKSPACE_KEK; an older deploy/.env without it must add one (openssl rand -base64 32) before upgrading, since the compose file always sets REDIS_URL. If the shared store is unreachable, each relay falls back to its own limits and logs it. /api/health rateLimitSharing.sharing says whether this relay’s limits are shared. With WORKSPACE_KEK set (the same key that seals workspace secrets), the sign-in lockout, the code budgets and the approval-card budget survive a relay restart through a Postgres copy keyed by a digest, never by an email or IP; without it they reset on restart. The compose file fixes REDIS_URL to the bundled valkey service and that value wins over deploy/.env, so to use another Valkey (or any Redis-protocol server) edit deploy/docker-compose.yml.
  • CORS. Set CYBORG_CORS_ORIGINS to the origins that should reach the relay.

Migrations

The relay does not apply migrations when it boots. The migrate service in deploy/docker-compose.yml applies them on every docker compose up, and you can run it by hand after pulling a new version:

cd deploy
docker compose run --rm migrate

Outside Docker, pnpm db:migrate runs the same entrypoint against DATABASE_URL. Pending migrations are applied and applied ones are skipped, so re-running is safe.

Connect machines

Once the relay answers GET /api/health, connect your machines with cyborg daemon claim or cyborg daemon join; see the self-hosting overview.