Skip to content

cc_server CLI

Every process flag takes a CLI flag or an environment variable; the flag wins, then the environment, then the default. Provider credentials are the exception — see Provider apps and Connect.

Flag Env Default Meaning
--data-dir CC_SERVER_DATA_DIR the OS per-user application-data dir (see below) Databases, secrets, models and cached media
--port CC_SERVER_PORT 9030 TCP port (0 = ephemeral)
--bind CC_SERVER_BIND loopback loopback, or any/all/0.0.0.0 for every interface (needs TLS or --insecure)
--repo-roots CC_SERVER_REPO_ROOTS the server user’s home directory Comma-separated base directories a client may browse when registering a repo. Browsing above a root is refused
--log-level CC_SERVER_LOG_LEVEL warning debug, info, warning, or error. The booting/ready lines always print
--server-name CC_SERVER_NAME the machine hostname Name shown in pickers, discovery and pairing surfaces
Flag Env Default Meaning
--tls-cert CC_SERVER_TLS_CERT unset PEM certificate chain. Serves wss:// in-process when set together with the key
--tls-key CC_SERVER_TLS_KEY unset PEM private key matching the cert
--insecure CC_SERVER_INSECURE off Allow a plaintext non-loopback bind. Only behind a TLS-terminating proxy on a trusted network; ignored when TLS is configured
--public-url CC_SERVER_PUBLIC_URL derived from the bind The RPC URL this server advertises to paired clients. Set this explicitly behind a proxy, NAT, or tunnel — the default is only a guess at the local bind
--allowed-origins CC_SERVER_ALLOWED_ORIGINS https://app.usectrl.dev Comma-separated browser origins allowed to dial /rpc cross-origin. Loopback and native clients are always allowed
--web-client-url CC_SERVER_WEB_CLIENT_URL unset Origin of the hosted web client that single sign-on callbacks bounce back to
--signaling-url CC_SERVER_SIGNALING_URL wss://signaling.usectrl.dev The relay broker this server joins so a phone can reach it with no direct path
--mdns CC_SERVER_MDNS auto LAN advertisement: auto (only when bound beyond loopback), on, off. Discovery advertises existence only — joining still needs pairing
--tunnel CC_SERVER_TUNNEL off Managed tunnel provider: off, cloudflared, ngrok, tailscale. Public exposure is opt-in
--tunnel-binary CC_SERVER_TUNNEL_BINARY resolved from PATH Explicit tunnel binary path
--tunnel-sha256 CC_SERVER_TUNNEL_SHA256 unset Expected SHA-256 of that binary, verified before every spawn
--tunnel-args CC_SERVER_TUNNEL_ARGS empty Comma-separated extra arguments for the tunnel invocation
Flag Env Default Meaning
--sandbox CC_SERVER_SANDBOX on on wraps agent runs in the host’s OS-native sandbox, and on a host without one starts only the server owner’s runs. off runs every member’s agents unconfined on this host. See below
--code-index CC_SERVER_CODE_INDEX on Field kill switch for background code-graph indexing. off boots clean without a rebuild
--code-index-defer CC_SERVER_CODE_INDEX_DEFER 15 Seconds to hold the first index sweep after the ready banner (clamped 0–300)
--tool-deferral CC_SERVER_TOOL_DEFERRAL on Whether harness runs send a small resident tool set plus a name index, loading the rest on first use. See below
--credential-gate CC_SERVER_CREDENTIAL_GATE 900 Seconds a run parks waiting for a human to fix a credential that cannot serve it (clamped 0–3600). See below

No build carries provider credentials. With Control Center Connect on, Connect runs every provider and these own apps stay saved but unused. Under Use my own apps, each provider runs on the server’s own app when one is fully configured, else it is unavailable. A workspace’s own app wins in either case. Own apps are set in Settings → Server → Single sign-on → Provider apps, or seeded once from the server’s .env file. There are no flags for them: a secret on a command line is readable through ps.

Variable Meaning
GITHUB_APP_ID The server’s GitHub App id
GITHUB_APP_PRIVATE_KEY Its private key, on one line with \n escapes. .env only
GITHUB_CLIENT_ID Its client id, for signing people in
GITHUB_CLIENT_SECRET Its client secret. .env only
GOOGLE_OAUTH_CLIENT_ID The server’s Google Web application client
GOOGLE_OAUTH_CLIENT_SECRET Its secret. .env only
LINEAR_CLIENT_ID The server’s Linear application (PKCE, no secret)
LINEAR_API_KEY A Linear service key for automation. .env only
KLIPY_APP_KEY The server’s own Klipy key for GIF search, used only under Use my own apps
CC_CONNECT_URL hosted, off, or a Connect URL. Locks the Connect choice; Settings then cannot change it
CC_SERVER_CONNECT_HOST on mounts Control Center Connect at <server>/connect, configured by CONNECT_* variables. See Run a Connect server

The .env file is read from the server’s working directory, beside the executable, or a source checkout above it; in Docker, mount it at /app/bin/.env. The server refuses to start (exit code 78) when GITHUB_APP_PRIVATE_KEY, GITHUB_CLIENT_SECRET, GOOGLE_OAUTH_CLIENT_SECRET, LINEAR_API_KEY or any SLACK_*SECRET* is exported in its process environment, where every child process could read it. Seeding from .env happens once per field, so a later edit in Settings is not undone by a restart. An empty value reads as unset.

No forge credential comes from the environment: GitHub, GitLab and Bitbucket all act on a member’s own sign-in or token, or on one-repository GitHub App tokens bounded by one.

The server probes the host once at boot and wraps agent command execution in the OS-native sandbox when a backend is available: sandbox-exec (Seatbelt) on macOS, bwrap plus socat on Linux and WSL2. The decision is made once and holds until the server restarts. There are three outcomes, each shown on the startup exposure line:

sandbox= When Whose agent runs start
native A backend is available and --sandbox is on Everyone’s, wrapped
off --sandbox off Everyone’s, unconfined on this host
unavailable --sandbox on and no backend (Windows, or Linux without bwrap and socat) Only runs the server owner is accountable for, unconfined. Others are refused with “This server has no sandbox, so only its owner can run agents here.”

For automation the accountable person is the one the automation is bound to. With no server owner recorded, no run starts on an unavailable host. On Linux and WSL2 with bubblewrap installed, native dispatch currently fails closed for every run; see Sandbox backends.

--sandbox off is the server owner’s choice for everyone who uses the server: it runs every member’s agents unconfined on this machine. Use it on a host where the sandbox profile itself misbehaves, or to let members run agents on a host with no backend. It does not need a rebuild, and the server logs a warning for the life of the process so the state is never silent.

Built-in harness runs send a small resident set of tool definitions plus a name-only index of the rest, which load their schemas the first time they are used. It cuts the tool block by roughly 78% and keeps the always-visible set inside the range where models select tools reliably. Deferred tools stay callable by name throughout, and search_tools finds them by intent. See Tool context and prompt caching.

--tool-deferral off makes every admitted tool resident again, reproducing the requests the server made before deferral existed. It is the kill switch for a model that handles the two-tier surface badly — a flag rather than a rebuild. It affects only the built-in harness; the MCP tools/list external clients see is always the full catalogue.

A run whose provider credential is missing or spent is parked rather than failed: the operator gets a prompt to fix it, and the run resumes if they do. The default deadline is 900 seconds (15 minutes), clamped to 0–3600.

The deadline is deliberately much longer than the approval prompt’s: an approval is a decision someone makes in seconds, while fixing a credential means opening a terminal, signing in and coming back. The ceiling is what keeps an unattended run — a pipeline step, a cron trigger, a webhook — from waiting on somebody who is asleep. When it expires, the run fails with the message it would have failed with anyway.

--credential-gate=0 is the kill switch: nothing is ever parked and a bad credential ends the turn exactly as it did before the gate existed.

Command What it does
cc_server Runs the server until SIGINT/SIGTERM
cc_server pair Provisions a device and prints its id and pairing key. Safe against a data dir a server is already serving — the running server picks the device up without a restart
cc_server connect <command> Shows or changes which Control Center Connect this server uses, without starting it
cc_server update Checks for, downloads and verifies a newer standalone release
cc_server --version Prints the build version and git SHA — the same identity /healthz and the RPC handshake advertise
Flag Default Meaning
--device web-client The device id. The platform is inferred from it, so --device desktop mints a desktop row and --device ios/android a phone row; anything else is treated as web
--label platform name plus this machine’s hostname Display name in the devices list
--host localhost, or <this-host> when bound to any interface Host to embed in the printed URL. Set it to the LAN IP or tunnel host a client will actually dial
--client-url unset Origin of the hosted web client. Adds a scannable deep link and terminal QR

pair also accepts the core --data-dir, --port and --bind flags: they select the data dir to write and shape the printed server URL (ws on loopback, wss when --bind any). Re-running pair for the same --device rotates its key and drops that device’s live sessions. A credential minted here has no expiry, unlike the 30 days an in-app pairing sets.

Reads and writes the same settings as the Control Center Connect card in Settings → Server → Single sign-on, from the data directory. A running server picks up a change within 10 minutes or on restart.

Command What it does
cc_server connect status Prints the mode, URL, whether CC_CONNECT_URL locks it, the install id, health and each lane’s source (own, connect or off)
cc_server connect enable Uses Control Center’s hosted Connect
cc_server connect enable --url <url> Uses a custom Connect at that URL (HTTPS, or http on loopback)
cc_server connect disable Stops using Connect. Only the server’s own apps sign people in

status with no command is the default. Each command accepts --data-dir. CC_CONNECT_URL overrides whatever these store. An unknown command exits 64. See Control Center Connect for the modes, install identity and status codes.

--apply replaces the install; it is refused while a server still answers on the configured port unless you pass --force. --allow-downgrade permits an older release.

The command refuses outright, with an explanation rather than an error, for installs it does not own:

Environment Detected by What it says
The desktop’s embedded server CC_EMBEDDED=1 or CC_BOOTSTRAP_DEVICE_ID Update the app instead — the installer swaps the whole tree
A dart run source checkout the script path ends in .dart Update it with git
Docker container markers Pull a newer image

cc_server runs until SIGINT / SIGTERM. One extra environment variable governs that, and it is set by the desktop rather than by you:

Variable Effect
CC_EXIT_WITH_PARENT=1 The server exits when its parent process does, detected by the parent closing the write end of its stdin pipe. The desktop sets it so a crashed app never leaves an orphaned server holding the data dir

Set it yourself only if you are supervising cc_server as a child process and want the same guarantee.

DO_NOT_TRACK=1 (any value other than empty, 0 or false) stops the server’s own usage analytics even when the server-wide switch is on. Clients still follow the switch.

The default data dir is ~/Library/Application Support/control-center on macOS, %APPDATA%\control-center on Windows and $XDG_DATA_HOME/control-center (else ~/.local/share/control-center) elsewhere. A cwd-relative .cc_server is only used when no home or app-data directory resolves.

The server keeps the data directory private to its own account (0700). It refuses to start (exit code 78) when it cannot, when global.db is damaged or was written by a newer version, or when its identity file cannot be read.

Path Contents
global.db The workspace registry, users, paired devices, the newsfeed and the fleet queue
<workspaceId>/workspace.db One database per workspace — agents, spaces, tickets, memory
<workspaceId>/code_index.db That workspace’s code graph. Rebuilt when it is missing, never backed up
pre_upgrade/, <workspaceId>/pre_upgrade/ The newest two copies of a database from before an update changed its format
<workspaceId>/chat_credentials/ Chat bot tokens, as plain JSON, so they go with the workspace
secrets.json Pairing keys, the Connect install key, provider apps, people’s sign-ins (sealed when made through Connect), webhook secrets, SSO (0600)
backups/<timestamp>/ One install snapshot — manifest.json, global.db and a copy of each workspace
backups/exports/ Single-workspace exports, <workspaceId>-<timestamp>.db
backups/transfer/ Staging for backup downloads and uploads; swept by the route that writes it
models/ On-device embedding, diarisation and speech models
meetings/<meetingId>/ Retained meeting audio
rigs/images/ Imported rig disk images (the QEMU desktop surface)
rigs/smolvm/<rigId>/ Per-rig microVM runtime state (the broker secret, 0600)
rigs/smolvm-packs/ Pre-extracted machine packs — the cache that makes repeat rig boots fast
rigs/tls/ The dev-domain certificate authority for rig HTTPS (keys 0600)
rigs/run/<rigId>/ QEMU overlays, seed images and per-VM keys (0600)