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 three 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, Integrations, 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.

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

Paths and outputs — Settings ▸ Paths & Outputs

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. Whether an override is honored depends on the owning daemon — and the Settings page badges the rows honestly:

The three "not honored yet" rows are disabled and badged exactly that way in Settings. They exist so the config surface is complete; setting them today has no effect.

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:

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.

Autostart — Dashboard ▸ Platform Health

autostart.* controls which background services launch with the app: the local graph server, the knowledge base, image generation, routines, the observer, and Voice. 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.

Integrations — Settings ▸ Integrations

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

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 in the runtime config retargets the account backend the desktop sign-in and entitlement flow talks to. Leave it null — that is the shipped state, and it resolves to the production account server. A non-null absolute origin is an advanced escape hatch for running a local account server against an installed build; it wins everywhere the sign-in flow runs. There is no Settings surface for it — edit the file.

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 — and reports a pass/fail table. Run it after any environment-file change that did not behave as expected. The check-by-check reference: Doctor checks.