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 |
Reachability and TLS
Section titled “Reachability and TLS”| 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 |
Indexing and runtime
Section titled “Indexing and runtime”| 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 |
Provider apps and Connect
Section titled “Provider apps and Connect”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.
--sandbox
Section titled “--sandbox”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.
--tool-deferral
Section titled “--tool-deferral”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.
--credential-gate
Section titled “--credential-gate”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.
Subcommands
Section titled “Subcommands”| 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.
connect
Section titled “connect”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.
update
Section titled “update”--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 |
Process lifecycle
Section titled “Process lifecycle”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.
Data directory layout
Section titled “Data directory layout”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) |
See also
Section titled “See also”- Run a headless server — the setup recipe these flags belong to
- Run a fleet worker — the separate
cc_workerbinary that registers with this server - Back up and restore — copying this directory somewhere safe
- Backup, export and import — the snapshot layout and every backup operation
- Connect to a remote server — pointing a client at one
- Deployment and clients — why the server owns everything