Reference
Configuration
Environment variables for the Cyborg7 daemon and for a self-hosted relay, with pointers to the canonical templates.
Cyborg7 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 |
PASEO_CLAUDE_DEBUG | optional | Verbose Claude stream logging (trace-level, per token) | 1 |
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).
The CLI has its own variables (CYBORG_HOST, CYBORG_TOKEN, CYBORG_HOME); they are listed in the CLI reference.
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) |
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 | recommended | Base64, 32 bytes. Encrypts stored integration tokens. Set it before connecting an integration |
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 | Shares rate-limit counters (and pub/sub fan-out) across relay instances. A single relay does not need it; set it before running more than one |
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. Defaults to https://app.cyborg7.com |
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 s3, set S3_ASSETS_BUCKET, S3_ASSETS_REGION and credentials (S3_ASSETS_ACCESS_KEY_ID, S3_ASSETS_SECRET_ACCESS_KEY). ASSETS_S3_PUBLIC_URL sets an optional CDN or read base. To serve signed CloudFront URLs, set CLOUDFRONT_DOMAIN, CLOUDFRONT_KEY_PAIR_ID and CLOUDFRONT_SIGNING_KEY together. ASSETS_REQUIRE_AUTH and ASSETS_STRICT_DELIVERY tighten who can read assets; see deploy/.env.example before enabling them.
Operations
RELAY_DRAIN_MS and RELAY_PRESENCE_COALESCE_MS tune restarts and presence updates. RELAY_METRICS_TOKEN turns on GET /api/metrics, and RELAY_METRICS_EMF=1 with RELAY_INSTANCE_LABEL emits one CloudWatch-format metrics line per minute. All are off or defaulted unless set, and none is hot-reloaded: restart the relay after editing.