Troubleshooting

Start with Doctor

Every troubleshooting session starts in the same place: Settings ▸ Doctor. Doctor runs the full health catalog against your install — binaries, Python runtimes, configuration files, daemons, the knowledge-graph backend, the video engines, media tools, and your account state — and shows one row per check, grouped into five sections:

How to read the results

Three states matter:

• Pass — the check verified the real condition (a binary answered on PATH, a daemon answered its health endpoint, a file exists where expected).
• Fail — something is genuinely broken and needs your action. Fail is reserved for real breakage: a missing prerequisite binary, a missing or partial platform tree.
• Info — a deliberate design choice worth understanding: "not started yet" is never treated as broken. A daemon that is not running, an engine you have not installed, an API key you have not set, or a check that cannot run because the daemon it needs is offline all show as info rows with a precise cause and, where possible, a one-click fix. An install with several info rows can be perfectly healthy.

Most rows carry a fix action (Start, Provision, Generate, Trust, Refresh). These delegate to the exact same operations the Dashboard's Platform Health card uses — there is no separate "Doctor-only" mutation path, so a fix applied here behaves identically to one applied there.

When the app itself will not start

The same checks exist as a zero-dependency terminal script that runs before anything is provisioned — no daemons, no Python packages required:

python scripts/doctor.py

Run it from your install root. It is the fallback diagnostic for the rare case where the desktop app cannot boot at all.

The clusters below map the Doctor catalog onto the problems buyers actually hit, in rough order of likelihood. A complete per-check reference is at Reference ▸ Doctor checks.

Runtime prerequisites — binaries and Python environments

Command Center's agentic layer rides four external binaries and six component Python environments. Doctor's Core group checks each one individually.

The six component environments are: shared-agent-memory, knowledge-base (which also serves the graph and Gemini tools), routines, observer, email-server, and imagegen. You do not need to create them by hand — the runtime provisioner bootstraps everything in one pass:

python scripts/provision_runtime.py

Run it from your install root. It installs uv, a pinned Python, and all six environments. It can take several minutes on first run (network plus interpreter download), which is why Doctor points you at the terminal command instead of offering a one-click fix for this row.

Two info states worth knowing:

• "cannot verify yet" on a binary row — the tool-detection command shipped in this build but needs one app restart to activate. Restart Command Center and re-run Doctor before concluding anything is missing.
• "the platform was updated since the last provision" on the Runtime provisioner row — an app update refreshed the platform tree, but Python environments are never touched automatically on update. Re-run the provisioner to pick up refreshed dependencies.

API keys — presence and reachability

No API key is required to boot Command Center. Two optional Gemini slots unlock specific capabilities, and Doctor checks both presence and whether the running services can actually use them.

Two rules explain most key problems:

1. Keys are read at process start. A key saved while a daemon is running is invisible to it until that daemon restarts. Doctor cross-checks the live daemon's own view and names this state explicitly.
2. Key writes are restart-bound. Settings ▸ API Keys writes your local .env file (and creates it on first save — the ".env configured" row passes from then on). After changing keys, restart the affected daemon (Dashboard ▸ Platform Health) or your agent session.

Daemon health

The platform's substance runs in local background daemons, all bound to loopback (127.0.0.1) only. Doctor's Daemons group probes each one's health endpoint.

A daemon being down never crashes the shell — dependent views go quiet and recover as soon as the daemon is back. Restarting a daemon from Platform Health is also the standard step after configuration changes, and it never requires restarting the app or your agent session. See Infrastructure ▸ Daemons for the full map.

Knowledge-graph backend (ArcadeDB)

The knowledge graph runs on ArcadeDB. The default mode is provisioned local: Command Center installs and manages its own no-Docker instance (a Java runtime plus a pinned package) inside your install. No container runtime is required.

The graph store is derived data — it is rebuilt from your files by root sync and re-ingest. A damaged graph is an inconvenience, never data loss; your documents are the source of truth. See Concepts ▸ Knowledge graph.

Sign-in and subscription

Command Center requires sign-in with an active Pro or Ultra subscription. Verification happens online, periodically — and the product is designed to degrade politely, not punish you, when you are offline.

If a refresh fails while you are demonstrably online, check that your subscription is active, then contact support with the exact Account row text.

Hooks, terminals, and folder trust

Two agent-harness conveniences ride hook scripts installed into your agent configuration — and uninstalled hooks fail silently, which makes them a classic "nothing errored, it just stopped happening" case.

Install and update recovery

These rows cover the install's structural integrity — the platform tree, the generated agent configuration, and the doctrine files.

For the full picture of what an update does and does not touch, see Concepts ▸ How updates work.

Video engines and media tools

The two video engines are opt-in installs — a fresh install without them is the normal state, not a problem.

Still stuck?

Check the FAQ for the questions that come up most, or contact support — include your Doctor findings and the app version, and you will get a substantive answer rather than a canned one.