Skip to content

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.

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-server image ships CC_SERVER_INSECURE=1 (it must bind 0.0.0.0 to 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 set CC_SERVER_TLS_CERT / CC_SERVER_TLS_KEY (then unset CC_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 with docker run -e … or the compose environment: block.

  • /data is 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 when GITHUB_APP_PRIVATE_KEY, GITHUB_CLIENT_SECRET, GOOGLE_OAUTH_CLIENT_SECRET, LINEAR_API_KEY or a SLACK_*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_PORT overridable); it is stateless, holds no pairing keys and is a fallback — a phone uses loopback, LAN, tailnet or a direct wss:// 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.

  • 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, plus meson, ninja, pkg-config, git and 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.

The natives are required — there is no degraded mode. Build them from the repo root before anything else:

Terminal window
scripts/natives/build_natives.sh

This 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.

Terminal window
cd apps/cc_server
fvm dart build cli

The 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.

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:

Terminal window
./build/cli/<os_arch>/bundle/bin/cc_server pair --data-dir ./data --port 9030

It 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:

Terminal window
./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.dev

A 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.

On loopback — the default and all you need for a client on the same machine:

Terminal window
./build/cli/<os_arch>/bundle/bin/cc_server --data-dir ./data --port 9030

To 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:

Terminal window
./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/rpc

Or terminate TLS in a reverse proxy on a trusted private network and opt into a plaintext bind behind it:

Terminal window
./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.

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 without bwrap and socat), 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.

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.

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:

Terminal window
node tool/stage_resource_assets.mjs build/web

For 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.

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:

Terminal window
./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 ./data

CC_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.

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.

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 unknown Host, or a POST that is not JSON are refused before the token is checked. See Use the MCP server.
  • GET /healthz is 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 reachable cc_server discloses that much to anyone who asks.