Run a headless server
Run cc_server on a machine that stays on, then connect to it from your desktop,
a browser, or your phone. The server is a pure-Dart native binary — no Flutter
engine — so it runs headless on macOS, Linux, or Windows. It owns the database,
runs the agents and makes every external API call; the clients only render.
Run in Docker (prebuilt images)
Section titled “Run in Docker (prebuilt images)”Every release publishes a self-hosted stack of four GHCR images — the backend,
the two static thin clients and the optional pairing relay — plus the optional
cc-connect sign-in service (Run a Connect server)
and a separate cc-server-demo image for the public demo host. A self-hosted install needs
no source checkout. Pin a version tag (ghcr.io/samuelalev/<image>:v0.0.1-rc.1)
or ride latest.
| Image | What it is | Publishes |
|---|---|---|
ghcr.io/samuelalev/cc-server |
The backend: database, agents, MCP, webhooks | -p 9030:9030 |
ghcr.io/samuelalev/cc-webapp |
The web client (static nginx) | -p 8080:8080 |
ghcr.io/samuelalev/cc-remote |
The phone companion PWA (static nginx) | -p 8081:8080 |
ghcr.io/samuelalev/cc-signaling-server |
The encrypted connection relay (optional) | -p 8788:8788 |
The whole stack as a compose file:
services: server: image: ghcr.io/samuelalev/cc-server:latest ports: ["9030:9030"] volumes: ["cc_data:/data"] restart: unless-stopped web: image: ghcr.io/samuelalev/cc-webapp:latest ports: ["8080:8080"] restart: unless-stopped remote: image: ghcr.io/samuelalev/cc-remote:latest ports: ["8081:8080"] restart: unless-stopped signaling: image: ghcr.io/samuelalev/cc-signaling-server:latest ports: ["8788:8788"] restart: unless-stopped
volumes: cc_data:Things worth knowing before you expose any of this beyond loopback:
-
The
cc-serverimage shipsCC_SERVER_INSECURE=1(it must bind0.0.0.0to receive published-port traffic). Use a TLS-terminating reverse proxy — Caddy, Traefik, nginx or a Cloudflare Tunnel — on a trusted network, or mount a certificate and setCC_SERVER_TLS_CERT/CC_SERVER_TLS_KEY(then unsetCC_SERVER_INSECURE). This setting controls only the server’s outer HTTP/WebSocket listener. It never disables the mandatory end-to-end encrypted client session. TLS still protects login/bootstrap traffic, connection metadata, public endpoints and web-client delivery. Everything is overridable withdocker run -e …or the composeenvironment:block. -
/datais the only state. The SQLite databases, paired-device secrets, downloaded models and meeting audio all live in the volume — back it up and the container becomes disposable. -
Provider secrets go in a mounted
.env, never-e. The server refuses to start whenGITHUB_APP_PRIVATE_KEY,GITHUB_CLIENT_SECRET,GOOGLE_OAUTH_CLIENT_SECRET,LINEAR_API_KEYor aSLACK_*SECRET*is in its process environment. Mount the file read-only at/app/bin/.env(-v /secure/cc.env:/app/bin/.env:ro), or configure the apps in Settings. -
Pair a client from inside the image before the first connection, the container equivalent of step 3:
Terminal window docker run --rm -it -v cc_data:/data \--entrypoint /app/bin/cc_server ghcr.io/samuelalev/cc-server:latest pair -
The two client images are static nginx hosts. Embedded browser editors use the same app origin and encrypted connection, as described below. Each client’s connect form takes your server URL, device id and pairing key. The signalling relay needs only its port (
SIGNALING_HOST/SIGNALING_PORToverridable); it is stateless, holds no pairing keys and is a fallback — a phone uses loopback, LAN, tailnet or a directwss://path when one is reachable, and only falls back to the relay when none is. Skip it if your clients always reach the server directly. The broker can see routing identifiers, IP addresses, sizes and timing, and can interrupt traffic; it cannot decrypt the client/server resource stream.
The rest of this guide builds the server from source; the flags and behaviour it covers are the same ones the image’s environment variables feed.
Prerequisites
Section titled “Prerequisites”- The Dart SDK. This repo pins its SDK with fvm, so prefix every command with
fvm. - This repository checked out.
- The native toolchain the staging script needs — Rust/
cargo, plusmeson,ninja,pkg-config,gitand a C++ compiler. Each build script names what it cannot find and how to install it. - A reachable host: loopback for local use, or a LAN/public address with TLS for remote clients.
Step 1: Stage the native libraries
Section titled “Step 1: Stage the native libraries”The natives are required — there is no degraded mode. Build them from the repo root before anything else:
scripts/natives/build_natives.shThis builds rift, fff, tree-sitter plus its grammars, aec, lame,
ccpty, cc_watcher, cc_inference and the SAML native into
build/natives/. The cc_server build
hook re-emits whatever is staged there into the bundle, so skipping this step
either fails the build outright or — with the escape hatch below — produces a
binary whose boot preflight refuses to start and names the missing library.
Step 2: Build the binary
Section titled “Step 2: Build the binary”cd apps/cc_serverfvm dart build cliThe bundle ships libsqlite3 and the staged natives alongside the binary — no
system SQLite and no Flutter engine needed. The executable lands at
./build/cli/<os_arch>/bundle/bin/cc_server.
Step 3: Pair a client before first start
Section titled “Step 3: Pair a client before first start”A fresh data directory has no paired device and no pre-shared key, so a client’s
pairing-key prompt cannot be satisfied yet. Mint one with the pair subcommand.
It writes global.db and secrets.json directly; a server that is already
serving that data dir picks the new device up without a restart:
./build/cli/<os_arch>/bundle/bin/cc_server pair --data-dir ./data --port 9030It prints three values to paste into a client’s connect form:
Connect a thin client (paste into its connect form): Server ws://localhost:9030/rpc Device id web-client Pairing key <a freshly generated key>Useful flags: --device (default web-client; the id also picks the device
tier — desktop, ios, android, anything else is a web client), --label
(defaults to the platform name plus this machine’s hostname), --host (the host
to print in the URL, since loopback is not reachable from another machine) and
--client-url. Re-running pair rotates that device’s key and drops its live
sessions. Pairing never creates a workspace. Only the server owner creates
workspaces: on the owner’s client, onboarding names and creates the first one,
and anyone else waits until the owner creates one for them or a workspace admin
invites them.
With --client-url it also prints a terminal-scannable QR that opens the web
client already filled in:
./build/cli/<os_arch>/bundle/bin/cc_server pair --data-dir ./data --port 9030 \ --bind any --host 192.168.1.42 --client-url https://app.usectrl.devA credential minted by cc_server pair expires after 30 days, like one minted
in the app; run pair again for the same device to issue a fresh one. Revoke a
CLI-minted device from Settings → You → Your devices when you are done with
it.
The pairing key authenticates the mandatory Noise handshake; each session derives fresh traffic keys and checks the server’s signed identity. Protect the pairing key and get it from a trusted source (including a trusted QR), then verify a new server fingerprint through a separate trusted channel or against a known pin. Do not silently accept a changed pin: re-pair through a trusted channel if you intentionally replace the server identity. TLS by itself cannot establish that end-to-end identity pin.
Step 4: Start the server
Section titled “Step 4: Start the server”On loopback — the default and all you need for a client on the same machine:
./build/cli/<os_arch>/bundle/bin/cc_server --data-dir ./data --port 9030To reach it from another machine, bind every interface. A non-loopback bind
without TLS is refused at startup (Refusing to bind non-loopback address … without TLS), so supply a certificate:
./build/cli/<os_arch>/bundle/bin/cc_server --data-dir ./data --port 9030 \ --bind any --tls-cert /path/fullchain.pem --tls-key /path/privkey.pem \ --public-url wss://server.example:9030/rpcOr terminate TLS in a reverse proxy on a trusted private network and opt into a plaintext bind behind it:
./build/cli/<os_arch>/bundle/bin/cc_server --data-dir ./data --port 9030 \ --bind any --insecure --public-url wss://server.example/rpc--insecure is ignored when --tls-cert and --tls-key are both set — TLS
always wins. The server advertises the outer listener’s plaintext state as
insecure: true in GET /healthz. This does not turn off Noise encryption
on /rpc, whether the client connects directly or through the relay. Upgrade
the server, relay and clients together: old plaintext RPC clients are rejected,
with no compatibility fallback. Public requests to sensitive resource routes
(including backup transfers) get HTTP 426, even from loopback; paired clients
use the encrypted tunnel instead.
The server runs until SIGINT/SIGTERM, then shuts down cleanly.
Read the startup lines
Section titled “Read the startup lines”Two lines tell you how this server is set up. The exposure line, printed next
to the ready banner, starts with cc_server exposure: and lists how far it can be reached (bind, tls,
relay, tunnel), whether a server owner is recorded (owner), and how
agents run on this machine (sandbox):
sandbox=native: every agent run is wrapped in the OS sandbox.sandbox=off: you started the server with--sandbox off, so every member’s agents run unconfined on this machine.sandbox=unavailable: the host has no sandbox backend (Windows, or Linux withoutbwrapandsocat), so only agent runs the server owner is accountable for start. Everyone else’s runs are refused with “This server has no sandbox, so only its owner can run agents here.”
A sandbox line earlier in the log says the same in words and, when a backend is
missing, names what to install. Running other people’s agents without a
sandbox is a choice the server owner makes once, for everyone, with
--sandbox off. See Configure sandbox policies.
Step 5: Connect a client
Section titled “Step 5: Connect a client”Point a client at the server URL and pairing key from step 3:
- Desktop app: on the first-run screen click Connect to a server, or add the server later at Settings → Server → Connection & status. See Connect to a remote server.
- Web client: open app.usectrl.dev (or your own copy of the web build), click Connect to a server, and enter the server URL and, under Use a pairing key, the device id and pairing key.
- Phone: pair the Remote app from a running client — see Pair a device.
Browser editor resources
Section titled “Browser editor resources”The editor frontend is trusted application code and runs on the web app’s own
origin. Its Service Worker routes HTTP and WebSocket traffic through the same
authenticated encrypted session as the rest of the client. cc_server
decrypts each request, forwards it to its local code-server backend, and
encrypts the response back to the client. The files remain server-owned.
The editor runs on the server as the server’s own user, with its terminal, tasks and extensions, so only the server owner can open it. A session belongs to the device and person that opened it. It opens with VS Code’s workspace trust on, so VS Code asks before trusting a folder, and with automatic tasks off, so a repository’s tasks never start on open. Everyone else keeps the app’s built-in editor and file views; the full editor is not offered to them.
Host the web client over HTTPS or a secure loopback origin so Service Workers can run. The normal web build and release scripts include the shared resource assets. If you build a bundle manually, stage those assets afterwards from the repository root:
node tool/stage_resource_assets.mjs build/webFor the phone web build, substitute apps/cc_remote/build/web. This copies
cc_resource_bridge.js, cc_resource_worker.js and cc_resource_ws_shim.js
into the app bundle.
Native editor traffic uses a capability-scoped loopback facade instead. Do not expose the server-launched editor extension’s private loopback report/command gateway through a public proxy. Sensitive public HTTP requests are rejected; resources require an authenticated encrypted session.
Step 6: Choose how people sign in
Section titled “Step 6: Choose how people sign in”The first client to connect as the server owner is asked how this server signs people in to GitHub, Google Calendar and Linear: Use Control Center’s apps, Use my own apps, or Use a custom Connect server. From the terminal, the same choice is:
./build/cli/<os_arch>/bundle/bin/cc_server connect status --data-dir ./data./build/cli/<os_arch>/bundle/bin/cc_server connect enable --url https://connect.example.com --data-dir ./data./build/cli/<os_arch>/bundle/bin/cc_server connect disable --data-dir ./dataCC_CONNECT_URL (hosted, off or a URL) in the server’s environment or .env
pins the choice instead. With Use my own apps, register each provider in
Settings → Server → Single sign-on → Provider apps; Create my GitHub App
sets up GitHub in one step. Provider secrets belong in the server’s .env file,
never the exported environment. See Create the GitHub App
and Control Center Connect.
Sign-ins through Connect finish with a code the browser shows, so the server
needs no public address for them. Sign-ins through the server’s own apps return
the browser to the server’s public URL, so set --public-url to an address
people’s browsers can reach.
This is the server’s default. A workspace admin can give one workspace a
different choice under Settings → Workspace → Integrations. With
CC_CONNECT_URL set, a workspace can still switch to its own apps but not to
a Connect of its own; see
Per-workspace choice.
To host Connect for other servers from this one, set CC_SERVER_CONNECT_HOST=on;
see Run a Connect server.
Configuration
Section titled “Configuration”The flags used above are the ones a first setup needs. The complete surface — 23
flag and environment-variable pairs, the four subcommands and the data-directory
layout — is in the cc_server CLI reference.
The four you are most likely to need:
| Flag | Default | Meaning |
|---|---|---|
--data-dir |
the OS per-user application-data dir | Databases, secrets, models and cached media |
--port |
9030 |
TCP port (0 = ephemeral) |
--bind |
loopback |
loopback, or any for every interface (needs TLS or --insecure) |
--public-url |
derived from the bind | The RPC URL advertised to paired clients. Set this explicitly behind a proxy, NAT, or tunnel |
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.
What the server serves
Section titled “What the server serves”cc_server is the whole product surface, not a subset: the repo-RPC data path
and subscriptions, the MCP tool endpoint at POST /mcp and GET /sse on the
same port, inbound webhooks, the media and font proxies, single sign-on
callbacks, the fleet lease protocol, server-side RSS fetching on a 30-minute
schedule and vector search (the sqlite_vector extension is registered as a
process-global auto-extension, degrading to full-text search only where the
extension is unavailable).
The dispatcher is stateless: there is no per-session workspace binding.
Every workspace-scoped call carries its own workspace_id and access is decided
by the caller’s workspace membership and role — not by holding a pairing key.
Two things to know before you expose the port beyond loopback (TLS alone does not provide the paired client’s end-to-end encryption or authorise resources):
- MCP always needs its token. The server creates the MCP token at first start and every request, loopback included, must send it as
Authorization: Bearer <token>. It cannot be turned off; the server owner reads and rotates it in Settings → Server → MCP servers. Requests from a web page, to an unknownHost, or aPOSTthat is not JSON are refused before the token is checked. See Use the MCP server. GET /healthzis unauthenticated by design, with wildcard CORS and publishes the server’s id, name, identity fingerprint and build version. Clients need the fingerprint to pin the server, so this is deliberate — but it does mean any reachablecc_serverdiscloses that much to anyone who asks.
Related guides
Section titled “Related guides”- Connect to a remote server
- Pair a device
- Run a fleet worker
- Connect a Google Calendar
- Run a Connect server