Troubleshooting

Start with Doctor

Every troubleshooting session starts in the same place: Settings ▸ Doctor. It stays available whatever your account state — signed out, lapsed, or fully verified — because it is the surface that fixes exactly those problems.

Doctor runs the full health catalog against your install and shows one row per check, in these groups:

How to read the results

Three result 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 — a prerequisite is genuinely missing: a binary that is not on PATH, a missing environment file, a runtime environment that was never created or whose interpreter is broken, or a missing or partial platform tree. Nothing else in the catalog can fail.
• Info — a deliberate design choice worth understanding: "not started yet" is never treated as broken. A daemon that is not running, a component you skipped, an engine you have not installed, an API key you have not set, a control plane you switched off, 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, Repair, Generate, Trust, Fetch, Enable, 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. The per-check reference is at Reference ▸ Doctor checks.

Runtime prerequisites — binaries and Python environments

Command Center rides a small set of external binaries, and runs its own Python side in per-service environments it installs itself. Doctor splits these: the Core group checks the binaries, and the Runtime group owns everything Python.

Use the Provision button

Doctor's Runtime group installs and repairs; it does not only report.

• Provision on the Runtime provisioner row installs uv, a pinned Python, and every missing environment in one pass. Expect several minutes on first run — it downloads an interpreter.
• Re-provision on the same row rebuilds against refreshed dependencies.
• Provision / Repair on an individual environment row targets just that one.

The command-line equivalent still ships:

python scripts/provision_runtime.py

Run it from your install root. Reach for it when the app will not open — when it does open, the buttons do the same work and report progress.

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.
• "platform updated since last provision" on the Runtime provisioner row — an app update refreshed the platform tree, but Python environments are never touched automatically on update. Re-provision to pick up refreshed dependencies.

A component you skipped

Command Center asks during first-run setup which parts it should install for you, and everything is on unless you say otherwise. If a capability never appears and no row explains why, check Doctor's Components group first: a skipped component shows as an info row naming exactly what stops working, with an Enable button beside it.

Skipping never deletes anything already installed — it only stops future automatic provisioning — and it is never a lock: pressing an install button elsewhere on the board proceeds anyway, because asking for the install is the act of enabling it.

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

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. 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 rather than punish you when it cannot reach the account service.

How long a machine works offline: up to 72 hours from its last successful verification. Verification renews automatically at the halfway point, so an install that loses contact keeps working somewhere between 36 and 72 hours depending on when it dropped. There is no additional grace period after that. App updates are governed separately and tolerate a staler record — a few extra days — so security patches keep arriving after feature access has paused.

While you are verified, Settings ▸ Account states this plainly: when the record was last confirmed, that it renews automatically, and how much longer the machine works without reaching the service.

When verification is not current, Doctor's Account row reads degraded (<reason>) — treated as unsubscribed, and the reason is what tells you what to do:

Nothing is deleted in any of these states. Your files, configuration, and local data are untouched, and everything unlocks again on the next successful verification.

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

Something refused

These are the cases where the product is working exactly as configured and still says no. None of them is a fault; all of them are hard to diagnose without knowing where the switch is.

What each plane governs, why they fail open, and what is recorded is on Autonomy and controls.

Nothing is happening on a fresh install

A brand-new install is deliberately quiet. Nothing schedules itself, so an install that looks complete and does nothing is usually behaving correctly.

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.

Platform-specific behaviour

Two classes of symptom come from the machine rather than from Command Center. Both look like product faults and neither is.

Cortex draws no graph, but everything else in the view works

The graph canvas is GPU-rendered. Before drawing, Command Center tests whether this system can actually allocate what the renderer needs — not merely whether it claims to support it, because the two come apart on precisely the machines this affects. When the test fails, the canvas is replaced by an explanatory panel naming the reason and, where readable, the detected renderer.

Common causes: a virtual machine or virtual desktop with a paravirtual display adapter, an RDP or screen-shared session, hardware acceleration disabled by policy, or a very old or blocklisted graphics driver.

Everything else keeps working, and this is the point of the design. The knowledge graph itself is unaffected: Overview, Report, Lint and Log read the same data without a GPU, ingestion and search are untouched, and agents query the graph directly. There is deliberately no low-fidelity 2D fallback — a misleading picture of your graph would be worse than an honest panel.

The remedy is a host with working acceleration: enable hardware acceleration where policy allows it, connect to the machine locally instead of through a remote session, or use a machine with a GPU. See Cortex.

macOS

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.