Reference
Configuration
Environment variables for the Cyborg daemon and for a self-hosted relay, with pointers to the canonical templates.
Cyborg has two pieces you can configure, and they read different variables.
- The daemon is the process on a machine that runs agents. It needs almost nothing to start.
- The relay is the server that owns the shared database and connects machines, browsers and the desktop app. You only configure one if you self-host.
Variables are set in the environment of the process (or in a .env file). With Docker Compose, deploy/.env is passed to the relay container; values fixed in the compose environment: list (such as REDIS_URL) win over it. Generate secret values and keep them out of version control.
Daemon
The daemon’s state directory and listen address are the two settings most people touch. Flags on cyborg daemon start (see the CLI reference) override them.
| Variable | Status | Description | Example |
|---|---|---|---|
PASEO_HOME | optional | Where the daemon keeps its state (agents, local database, config). Defaults to ~/.cyborg7. CYBORG_DAEMON_HOME is the same | ~/.cyborg7 |
PASEO_LISTEN | optional | Daemon listen address: host:port, a path, or unix:///path/to/socket. Defaults to 127.0.0.1:6780 | 127.0.0.1:6780 |
OPENAI_API_KEY | optional | For voice features (speech-to-text and text-to-speech), if you use them | sk-... |
Agents use the sign-in of the provider you pick on that machine (for example Claude Code or Codex), not a key you set here. To sign a machine in, use cyborg provider:sign-in (see the CLI reference). Agents on local models use the machine’s own model servers; a server that needs a key gets a key file, set in config.json as described in Local models.
The CLI has its own variables (CYBORG_HOST, CYBORG_TOKEN, CYBORG_HOME); they are listed in the CLI reference.
Local models
The daemon’s config.json (in its state directory, ~/.cyborg7 by default) can list the model servers its agents may use, under localModels. Without it, Cyborg still finds Ollama, LM Studio, llama.cpp, vLLM and SGLang on their usual ports on 127.0.0.1. See Run agents on local models.
"localModels": {
"autodetect": true,
"allowLan": false,
"endpoints": [
{
"id": "spark-thinker",
"label": "Spark thinker",
"baseUrl": "http://127.0.0.1:8001",
"apiKeyFile": "~/llm/.api_key",
"shared": false
}
]
}
| Key | Default | Description |
|---|---|---|
autodetect | true | Look for servers on the usual ports (11434, 1234, 8080, 8000-8010) of 127.0.0.1 |
allowLan | false | Allow baseUrl on a private network address (10.x, 172.16-31.x, 192.168.x, 100.64-127.x). Link-local addresses (169.254.x.x, fe80::) are always refused |
endpoints | none | Up to 16 servers to use besides the detected ones |
endpoints[].id | from port | Lowercase letters, digits and dashes, up to 40. Agents name their model by it, so keep it when the port changes |
endpoints[].label | engine and port | The name the app shows, up to 60 characters |
endpoints[].baseUrl | required | http or https, an IP address or localhost (read as 127.0.0.1), no user name, query or path other than /v1. Loopback only unless allowLan is set |
endpoints[].apiKeyFile | none | Path on this machine to a file that holds the key (absolute, or starting with ~/). A regular file of at most 4 KB; keep it chmod 600. There is no field for the key itself |
endpoints[].shared | false | Let people with run access to this machine, not only its owner and admins, start agents on a server that has a key |
The daemon refuses to start with an invalid localModels block and names the field (for example localModels.endpoints.0.baseUrl). A change to the file needs cyborg daemon restart; cyborg daemon reload lists the changed localModels.* settings (for example localModels.endpoints) among those that need a restart. Servers added or removed from the app or with cyborg machine:local-server-add take effect at once.
New agents can pick a local model only while features.localOpenCode is true (default false); it is read at start, so it also needs cyborg daemon restart. Agents already on a local model run either way. See Turn on local models.
"features": {
"localOpenCode": true
}
Before going back to an older Cyborg, remove features.localOpenCode and the localModels block: an older Cyborg checks features and the file’s top-level keys strictly and refuses to start with a config.json that has a key it does not know.
Relay (self-hosted)
The canonical list of relay variables, with what each one does, is deploy/.env.example in the repository. It changes with the relay, so treat it as the source of truth. The Docker guide walks through the variables you must set. The main ones:
| Variable | Status | Description |
|---|---|---|
DATABASE_URL | required | PostgreSQL connection string. The relay owns the shared database |
CYBORG7_JWT_SECRET | required | Secret that signs auth tokens, at least 32 characters. The relay refuses to boot on a public interface with a missing, short or public-default value |
RELAY_PUBLIC_URL | required | The https:// origin browsers use to reach the relay, no trailing slash. Compiled into the web UI, so changing it means rebuilding the image |
RELAY_HOST / RELAY_PORT | optional | Bind host (default 0.0.0.0) and port (default 9100) |
RELAY_TRUSTED_PROXY_CIDRS, RELAY_TRUSTED_PROXY_HOPS | optional | Which socket peers may set X-Forwarded-For, and how many proxy hops to trust. See Client IP behind a proxy |
CYBORG_MIN_CLI_VERSION | optional | Oldest cyborg CLI release (x.y.z) the relay asks for; cyborg doctor and the daily check warn below it |
CYBORG7_DAEMON_TOKEN_SECRET, CYBORG7_REFRESH_TOKEN_SECRET | recommended | Signing secrets for daemon and refresh tokens. tools/gen-selfhost-secrets.sh generates them alongside the JWT secret |
CYBORG7_TOKEN_ENC_KEY | required | Base64, 32 bytes. Encrypts stored integration tokens. A production relay refuses to boot without it |
RESEND_API_KEY, EMAIL_FROM | production | Sending sign-up and password-reset one-time codes |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET, OAUTH_LOGIN_CALLBACK_BASE | optional | Sign-in with Google and GitHub |
PG_SSL_MODE, PG_SSL_ROOT_CERT | optional | Postgres TLS: auto (default), verify-full or disable; a PEM path to verify against a custom CA |
REDIS_URL | optional | Valkey (Redis-protocol compatible) URL; the name is kept. Pub/sub fan-out across relay instances and the shared rate limits. Requires WORKSPACE_KMS_KEY_ID or WORKSPACE_KEK, or the relay refuses to start. If Valkey is down, limits fall back to per relay (logged). Use one Valkey per environment |
CYBORG_CORS_ORIGINS | optional | Comma-separated allowed origins for the relay’s HTTP and WebSocket endpoints, for example https://app.example.com |
CYBORG_APP_URL | optional | App URL the relay uses in links and redirects (invite emails too). The self-host compose file defaults it to RELAY_PUBLIC_URL; otherwise https://app.cyborg7.com |
CYBORG7_SECRET_SCAN_BUDGET_MS | optional | Milliseconds one request may spend scanning text for secrets before the rest is sealed whole (default 150, whole number from 1 to 10000). A bad value stops the relay at boot |
CYBORG7_DEV_ECHO_OTP | dev only | Returns the sign-up or reset code in the API response instead of emailing it. Never set it on a relay anyone else can reach |
Asset storage
Uploads (avatars and attached files) go to the backend named by ASSETS_BACKEND:
| Value | Behaviour |
|---|---|
s3 (default) | AWS S3, or any S3-compatible server such as MinIO via ASSETS_S3_ENDPOINT |
fs | The relay’s own filesystem, served by the relay (ASSETS_FS_DIR, ASSETS_FS_PUBLIC_URL) |
For fs, set ASSETS_FS_PUBLIC_URL to the relay’s own public address, including any path prefix the relay is served under (for example https://example.com/relay for a relay behind /relay): Cyborg signs uploads and downloads under that address, so without the prefix they miss the relay.
For s3, set S3_ASSETS_BUCKET, S3_ASSETS_REGION and credentials (S3_ASSETS_ACCESS_KEY_ID, S3_ASSETS_SECRET_ACCESS_KEY). With a custom ASSETS_S3_ENDPOINT, ASSETS_S3_PUBLIC_URL is required: the S3 API origin browsers reach (scheme://host[:port], no path). Presigned uploads and downloads are signed for that host, so anything in front of it must pass Host and path through unchanged; a read-only CDN is not supported there. Without it, uploads and public asset URLs are off; with a path, uploads are refused. To serve signed CloudFront URLs, set CLOUDFRONT_DOMAIN, CLOUDFRONT_KEY_PAIR_ID and CLOUDFRONT_SIGNING_KEY together. Reading an asset always needs a signed-in caller (avatars excepted). ASSETS_STRICT_DELIVERY refuses delivery with no CloudFront signer; see deploy/.env.example before enabling it.
Operations
RELAY_DRAIN_MS and RELAY_PRESENCE_COALESCE_MS tune restarts and presence updates. RELAY_METRICS_TOKEN turns on GET /api/metrics. The relay always emits one CloudWatch-format metrics line per minute, and RELAY_INSTANCE_LABEL names its instance. All are defaulted unless set, and none is hot-reloaded: restart the relay after editing.