Configuration reference

Every Command Center setting is a value in a file under your install root (or in your per-user application-data directory). There is no hidden settings database. Which file a setting lives in decides when a change applies — some settings are hot and apply on the next operation, others need the affected component to restart. This page maps the configuration tiers, catalogs the keys you actually configure, and closes with the folder layout of an installed product.

The three configuration tiers

app/.env — keys and wiring (restart-bound)

The environment file is the home of everything secret or structural: API keys, the graph-database connection, daemon endpoints and ports, and optional harvest credentials. The annotated template ships next to it as app/.env.example; the live file is local to your machine and its values never leave it — Settings panels only ever report whether a secret is set.

Three consumers read this file:

1. The configuration sync — generates the install root's .mcp.json (the tooling manifest every agent session loads) from the environment file. Saving from any Settings panel re-runs it automatically.
2. The daemons — each background service reads its keys once, at process start.
3. The Settings view — the env-backed groups (API Keys, Database, Email, Daemons, Project) read and write the file directly.

Because every consumer reads it at startup, every change here is restart-bound: after a save, restart the affected daemon (Dashboard ▸ Platform Health) — running agent sessions pick the change up on their next launch. This is by design; anything that must apply live lives in the runtime config instead.

Generated files — never hand-edit. .mcp.json (and .mcp.http.json) at the install root are written by the configuration sync from the environment file. Direct edits are overwritten on the next save. To change what they contain, change the environment file.

config/cc.config.json — hot runtime settings

The runtime config lives at the install root under config/, deliberately outside the app tree. It is created from a shipped template on first run and never overwritten afterward. The app and the daemons read it lazily — per operation, not at boot — so a change applies on the very next operation, with no restart and no sync step.

Its contract keeps it safe to edit by hand:

• Every value is optional. A null or absent key means the built-in default — an untouched file is stock behavior exactly.
• Unknown keys pass through. A hand-added key is never dropped by a Settings save.
• Secrets and wiring do not belong here — they stay in the environment file.

Each section below has its own entry in the key catalog.

One section is read by the platform but not written into the shipped template: calendar. Absent means the defaults below, and you add the block by hand only if you want to change them.

Preference stores — per-view UI state

Per-view preferences — the UI theme, terminal pane behavior, session-resume switches, activity-log retention — live in small per-user files in your operating system's application-data directory, outside the install root. They apply immediately, persist across restarts, and are per-machine. You never edit these files directly; the owning view writes them (Settings ▸ Themes, Settings ▸ Terminals, the New Workspace dialog, and so on).

One note on precedence: for any value that is backed by the environment file, the environment file is authoritative — the app re-reads it at every launch. Preference stores only hold state that has no environment-file counterpart.

Key catalog

The curated list — the settings a buyer actually configures, grouped the way the product groups them. The Applies column tells you what, if anything, must restart.

API keys — Settings ▸ API Keys

The Gemini model and embedding identifiers (EMBED_MODEL, LLM_MODEL, GEMINI_MODEL, EMBED_DIM) also live in the environment file. The shipped defaults are correct; change them only if you know a newer model you want and accept re-embedding consequences.

Knowledge-graph backend — Settings ▸ Database

The knowledge graph runs on ArcadeDB in one of two backend modes. The mode itself is a hot runtime-config value; the connection profiles are environment-file values.

The two profiles share an HTTP port (2480) but not a database protocol port: the provisioned-local server listens on 7687, and the external profile ships pointed at 7688 so it cannot collide with an unrelated graph database on the conventional port. An unqualified "the database port" is the most common way to get a connection refused from a server that is running perfectly.

Paths and outputs — Settings ▸ Project

Output-tree relocations live in the runtime config (outputs.*). Blank means the default folder under the install root; set an absolute path to relocate that output tree, including onto another drive. The Settings rows badge how each one is picked up:

Two rules worth knowing before you relocate anything. Keep a tree that you want searchable inside documents/ — the knowledge graph walks that folder, and a tree moved outside it simply stops appearing there. And stateful data deliberately does not move with its output: the render-job history, for instance, stays in the project tree even when the media it describes lives on another disk.

Daemon endpoints and agent transport — Settings ▸ Daemons

Each background service derives its port from its own URL key, and the app resolves every call through the same key — change a URL and client and server move together. The host stays 127.0.0.1 (these are local child processes); the port is the knob. All changes apply after the affected daemon restarts.

Three related switches on the same page:

Agent control planes — Settings ▸ Terminals ▸ Agent control planes

One switch per plane, each answering a single question about what agents may do unattended. Every plane is on unless you turn it off, and every plane fails open: an unreadable config reads as on, so a stop is always something you turned on rather than something that arrived by accident. The model behind these switches — what a plane governs, what it records, and how it differs from your subscription — is Autonomy and controls. The keys:

The first two are held in memory by the servers that enforce them, which is why the switch acts immediately and the file's job is to remember the choice for next launch. The other three are read from the file on every call, so for those persisting the value is the live effect — including when you edit the file by hand.

control.email_send also stops your own composer. It is the one plane that is not agent-only: your Send does not go through the agent tool surface, but it does go through the same mail client underneath, and the stop lives inside that client. While the switch is off, nothing leaves this machine by mail — agent or human. If your own Send stops working while drafts still save and reading is fine, check this key first.

Terminals and the mission fleet — Settings ▸ Terminals

The remaining switches on this page are preference-store values (hot, per-machine): Auto-resume on restart and Keep agents warm (session resume), and the pane drag-to-reorder behavior. The two per-spawn agent toggles — skip permission prompts and auto-trust new folders — live in the New Workspace dialog, not in Settings.

Calendar — the Calendar header, and the file

The scheduling clock reads these on every request, so a hand edit applies to the next sweep. Only the first has a control in the app; the rest are file-edited, and the section is absent from the shipped template, so add it if you want to change them.

Whether anything fires and whether agents may write to the schedule are different questions with different switches: calendar.dispatchEnabled is the first, control.calendar above is the second, and neither implies the other.

Email — Settings ▸ Email and Email ▸ Agent

Mail is configured in two halves, on purpose. The account registry — who you are, which hosts, which mailboxes are enabled — is a hot runtime-config value you edit in Settings ▸ Email. The passwords are environment-file values: each registry entry names the environment key that holds its password rather than carrying the password itself.

The switches that decide how much the mail agent does on its own live in the same section, and their controls are in the Email view:

auto_approve_drafts is the one flag in this section that ships off, and deliberately: letting an agent answer a customer unattended is a decision you make, not one you inherit. control.email_send above sits over all of it as the master stop.

Components and install sources — Settings ▸ Doctor

components.* is your consent for what Command Center sets up on your machine. The first-run setup step and Settings ▸ Doctor ▸ Components are two views of this one section; every key defaults to enabled, and only an explicit false opts out.

An opt-out suppresses automatic provisioning only. An explicit Install in Doctor always proceeds and turns the flag back on — asking for the install is the act of enabling it — and opting out never removes something already installed.

source_preference.* answers the neighbouring question: when Command Center has both its own managed copy and one already on your system, which wins.

It only decides between installs that both exist — with one present, that one is used whatever you set. Both are hot: the next resolve re-decides, no restart. Set them from the Prefer control on the Node and ffmpeg rows in Settings ▸ Doctor ▸ Media.

Agent CLI defaults — Routines ▸ Global agent default

agent_cli.* is the install-wide default for unattended runs — routines, the Calendar's headless dispatches, harvest fan-out, the intelligence writers. Precedence, most specific first: a per-dispatch override, then the routine's own declaration, then this section, then the built-in default.

Saving from the Routines toolbar writes this one file and rewrites no routine definition, so switching back is exactly reversible. Choosing the alternative CLI requires it installed, signed in, and synced; a dispatch that cannot satisfy that is refused with a stated reason rather than run ungrounded.

Autostart — Dashboard ▸ Platform Health

autostart.* controls which background services launch with the app. The default is on for everything — a fresh install starts ready. Flip a service off from its Platform Health toggle; the change applies at the next app launch.

Newsletter and harvesting keys — Settings ▸ Email

All optional; leave any group blank to run without it. Applies after the consuming daemon restarts.

The harvesting inbox has two accepted spellings: the panel writes NEWSLETTER_IMAP_EMAIL and NEWSLETTER_IMAP_PASSWORD, while the environment template still lists the earlier NEWSLETTER_EMAIL and NEWSLETTER_PASSWORD. Both are read, so a file written either way keeps working.

Proxy — Observer ▸ Settings ▸ Proxy

The observer's residential-proxy credentials (PROXY_POOL_USER, PROXY_POOL_PASS, PROXY_ROTATING_URL) are environment-file values, but you configure them from the Observer view's own Settings panel, not the global Settings — it includes a provider preset, a connection test, and the transport toggles. Full setup, provider formats, and expectations: BYO proxy setup. Changes apply after the observer daemon restarts.

Project root — Settings ▸ Project

The active project directory — the workspace Command Center operates on. Set it with Settings ▸ Project ▸ Browse; it syncs to the file-access allowlist and every file-backed view, and new terminals open there. The optional PROJECT_ROOT environment key overrides the automatic resolution; leave it blank on a normal install.

Account server

account.base_url names the account service the desktop sign-in and entitlement flow talks to. Leave it null — that is the shipped state.

On an installed build the key has no effect: sign-in and entitlement always resolve to the production account service, and an override written into the file by hand is ignored. It exists for development builds of the app itself. There is no Settings surface for it, and nothing about a normal install requires one.

Advanced — shipped defaults you should know exist

The folder layout

The buyer's mental map of an installed product — what lives where under the install root. Depth on the documents/ workspace itself is in Your workspace and documents.

<install root>/
├── CLAUDE.md            the operating contract — every agent session reads it first
├── .claude/             the agent control plane
│   ├── agents/          agent definitions
│   ├── skills/          skill packages
│   ├── protocols/       the doctrine corpus (described, not reproduced, in this manual)
│   └── routines/        routine definitions
├── mcp-servers/         the MCP servers and background daemons
├── app/                 the desktop application
│   ├── .env             ★ keys + wiring (the environment file)
│   └── .env.example     the annotated template
├── config/
│   └── cc.config.json   ★ hot runtime settings (created on first run)
├── .mcp.json            generated agent-tooling manifest — never hand-edit
├── documents/           your working tree: reports, missions, news, context artifacts
├── arcadedb/            the provisioned-local graph server home (server · runtime · data)
├── remotion/            the programmatic video engine
└── hyperframes/         the HTML-first video engine

Highlights of the documents/ tree — the part that is yours:

Two things live outside the install root, in your per-user application-data directory: the app's window preferences and secrets mirror, and the per-view preference stores (theme, terminal behavior, session resume). They are per-machine by design and move with your user profile, not the install.

Verifying a configuration

Settings ▸ Doctor runs the readiness checks — environment file present, every placeholder resolved, tool interpreters on disk, the graph database reachable, each control plane's current state — and reports a pass/fail table with a fix action on the rows that have one. Run it after any change that did not behave as expected. The check-by-check reference: Doctor checks.