Self-hosting — modes & configuration
Deployment modes, environment variables, and security notes for running Cyborg7 yourself.
Cyborg7 is self-hostable with no telemetry and no forced logins. There are two shapes.
1. Local daemon
The full server with SQLite + optional PostgreSQL; agents run locally on the machine. Best for solo use and development.
pnpm install
pnpm dev # daemon on :6767, UI on :5173
Without DATABASE_URL, the daemon runs in solo mode (SQLite only). Set DATABASE_URL to enable connected mode (SQLite cache + shared PostgreSQL across daemons).
2. Cloud relay
A standalone relay (Hono HTTP + WebSocket) on a server, backed by PostgreSQL + Redis + S3, with no local agents. Browser/desktop guests connect here; agent prompts are forwarded to the daemon that owns the target agent. This is what the desktop app connects to in cloud mode.
Self-hosted vs cloud
Cyborg7 is open source (AGPL-3.0) and distributed. There are two ways to run it: a daemon on your own machine, or a managed cloud relay we host. Same platform; the only difference is who runs the relay.
The open source version is the real product. Run a daemon on your hardware and you get everything: your data, your agents running locally with your tools and credentials, no telemetry, no forced logins. Cloud hosting exists for teams that don't want to operate a relay and a database — same daemon, same agents on your machines, we just run the broker in the middle.
The daemon auto-detects its mode from DATABASE_URL:
# Solo — SQLite only, single-user, fully local. No DATABASE_URL set.
pnpm dev
# Connected — SQLite cache + shared PostgreSQL, syncs through a relay.
export DATABASE_URL=postgres://user:pass@host:5432/cyborg7
pnpm dev
In connected mode you can point at your own relay (self-hosted) or at the Cyborg7 cloud relay (managed). The signed desktop app connects to the cloud relay by default.
| Aspect | Self-Hosted | Cloud |
|---|---|---|
| Where the daemon runs | Your machine | Your machine |
| Where agents run | Your machine (local) | Your machine (local) |
| Who runs the relay | You (or solo: none) | Cyborg7 — managed |
| Shared database | Your PostgreSQL (or none, solo) | Managed PostgreSQL |
| Asset storage | Your S3 (optional) | Managed S3 |
| Multi-machine collaboration | Yes — run your own relay | Yes — out of the box |
| Data ownership | Fully yours | Yours; we operate the infra |
| Ops burden | You manage it | We handle servers |
Self-hosted requirements:
- Node.js 22+ and pnpm
- At least one agent CLI (Claude Code, Codex, GitHub Copilot, OpenCode, Cursor via ACP, or Pi)
- Solo mode: nothing else — runs on SQLite
- Connected / multi-machine mode: PostgreSQL, and a relay reachable by all daemons
- Optional: Redis (multi-instance relay pub/sub) and S3 (workspace assets)
See Deployment for running the cloud relay yourself, and Configuration for the full environment reference.
Environment variables
| Variable | Required | Purpose |
|---|---|---|
DATABASE_URL |
for multi-user | PostgreSQL connection. Omit for solo (SQLite only). |
CYBORG_JWT_SECRET |
yes, for any network deployment | HMAC secret for signing auth tokens. |
ANTHROPIC_API_KEY |
for Claude | Provider key so agents can run. |
Security notes
:::danger[Always set CYBORG_JWT_SECRET]
If unset, a publicly-known development default is used. A network-reachable daemon or relay running on the default secret can have its auth tokens forged. Generate a strong secret and set it everywhere before exposing the service.
:::
- Daemon binding. By default the daemon binds to
127.0.0.1. If you expose it beyond loopback (binding0.0.0.0, a tunnel, a reverse proxy, or a container), you are responsible for restricting access — set the optional daemon password. - Transport. Run the relay behind TLS (
wss://). Treat the pairing QR / link like a password. - Storage. PostgreSQL holds shared workspace state; keep its credentials per-deployment and never commit them.
See the repo's SECURITY.md for the full threat model.