👨⚕️ Doctor
In a nutshell
Inspect the host environment and capture a support report with
acorn doctor.
Start broad, then narrow the diagnostic category:
acorn doctor
acorn doctor --check software
acorn doctor --check system,memory,network
acorn doctor --report > acorn-doctor.json
Doctor reports use the same discovery-record JSON schema as the interactive Doctor screen. The software probes cover ACORN, Chromium, Codex, Codex ACP, Git, Node.js, npm, npx, OpenCode, Ollama, ORAS, Pandoc, and Vale.
If Codex ACP is reported as missing, install its executable globally and rerun the software check:
npm install -g @agentclientprotocol/codex-acp
acorn doctor --check software
This global installation does not require npx. If npm and npx are unavailable, install Node.js/npm or download a standalone binary from the codex-acp releases and place it on PATH.
--fix applies only reversible, low-risk automatic fixes and then reports the verified host state. Package-manager and network installers require --fix --interactive: select findings with Space, preview the fixed operations with f, and confirm with y. n or Escape declines the plan. --interactive without --fix remains report-only, and --report cannot be combined with interactive mode.
Rescue: ACORN cannot find Chrome
PDF export needs Chrome or Chromium. Point ACORN at an existing executable instead of relying on automatic discovery:
# Linux
acorn --offline export index.json --format pdf \
--chrome-path /usr/bin/google-chrome-stable
# macOS
acorn --offline export index.json --format pdf \
--chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
On Windows, pass the executable path with --chrome-path or set CHROME_PATH. Connected export can download ACORN’s pinned browser; offline export needs a configured, installed, or already cached browser. See Chrome selection.
Rescue: offline mode unexpectedly fails
Global --offline forbids network reads; it does not turn remote inputs into local ones. Check these common causes:
- Replace HTTP(S) inputs and model-list URLs with local paths or
file://URIs. - Use
check --skip proseif analyzer extensions have not already been synchronized. - Configure
--chrome-pathor cache the pinned browser before offline PDF export. - Do not combine
gather --resolve,gather --merge-request, orgather --ostiwith offline mode.
Run the failing command with -vv to expose the resource ACORN attempted to resolve.
Rescue: a model sync target is not detected
With no target flags, acorn sync selects applications whose commands it detects. Request a target explicitly to make the decision visible:
acorn sync --vscode --dry-run
acorn sync --vscode --force --dry-run
--force bypasses command detection only for targets you explicitly include. If the application is detected but weights are elsewhere, set --models-dir; use --assume-models only when another system guarantees those paths exist. Continue with the Sync troubleshooting guide.
Next stop: Preview application routing with Sync.