ancha doctor

ancha doctor checks that a project is ready for ancha run. It validates the config and scenes, starts the tools, runs your agent once against the first scene and reports which tools the agent actually reached. It cleans up afterwards and does not change latest.

ancha doctor [options]

Option	Description
`--agent <command>`	Override the configured agent command
`--no-agent`	Skip the agent trial and explicitly report incomplete agent verification
`--timeout <duration>`	Maximum diagnostic agent duration, at most 30s (default: ”10s”)

Example

ancha doctor

Output

pass  workspace: running locally (worlds in a server this command starts)
pass  node: Node 24.22.2; ancha 0.1.4
pass  config: Configuration is valid
pass  scenes: 1 scenes are valid
pass  runtime: Backend accepted every scene and released its diagnostic environments
pass  agent: Agent completed a bounded diagnostic trial (exited)
pass  native:slack: Observed a successful native slack API request from the configured agent
pass  native:github: Observed a successful native github API request from the configured agent
pass  native:datadog: Observed a successful native datadog API request from the configured agent
pass  native:pagerduty: Observed a successful native pagerduty API request from the configured agent
pass  business: Diagnostic scene checks passed
next: ancha run

What it checks

Check	Passes when
`workspace`	Says where the worlds run: locally, or on the hosted workspace you signed in to. See CLI overview.
`node`	Node.js is version 24 or later. The line also names the installed CLI version.
`config`	`ancha.yaml` is valid.
`scenes`	Every scene file is valid.
`runtime`	The server accepts every scene.
`agent`	The agent ran and exited within the time limit (default `10s`, at most `30s`).
`native:<tool>`	The agent made at least one successful call to that tool. Server health and a clean exit do not count.
`business`	The first scene’s checks passed.

A tool the agent did not reach is a warning, not a failure, and so is a failed scene check. Each warning carries a hint:

Output

warning  native:github: Successful native github API access was not observed
  configure the native SDK using ancha connect github; health and process exit do not prove agent access
warning  business: Diagnostic business checks failed; assess the agent separately from SDK connectivity
  ancha run --json, then ancha explain latest --json
next: ancha run

When the agent crashes or times out, agent fails and the output shows the end of its log.

Exit codes

Code	When
`0`	Every check passed, or only warnings remain. Also with `--no-agent` when the config, scenes and runtime are fine.
`2`	No agent command, an invalid config or scene, or a hosted server that rejected the API key.
`3`	The server or runtime failed, or the agent could not complete the diagnostic trial.

--json prints {"ok": true|false, "checks": [{"name", "status", "message", "hint"}], "next": [...]}. ok is false only when a check failed.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

ancha doctor

Example

What it checks

Exit codes

​Example

​What it checks

​Exit codes

Example

What it checks

Exit codes