Skip to main content
Exit codes and error codes are in Errors. Every error ends with a hint: line that names the next command; try it first.

​
Install and setup

There is no package called ancha on npm. With npx, use the full package name: npx -y @ancha-labs/cli@0.1.4 <command>. The short name works only after @ancha-labs/cli is installed globally (npm install -g @ancha-labs/cli) or in the project (npm install --save-dev @ancha-labs/cli). The instruction files ancha init writes say the same.
Ancha needs Node.js 24 or later. Check with node --version, then switch, for example with nvm install 24 && nvm use 24.
npm skipped the module’s install script, or Node was upgraded since the install. The hint gives the exact command: npm install -g --allow-scripts=better-sqlite3,esbuild @ancha-labs/cli. For a project install, approve the scripts with npm install-scripts approve better-sqlite3 esbuild, then npm rebuild better-sqlite3.
The CLI depends on better-sqlite3, which downloads a prebuilt binary for your platform. Where none exists, npm builds it from source and needs a C/C++ toolchain: Xcode Command Line Tools on macOS, or build-essential and Python on Linux.
Run ancha init in your agent’s project. It writes ancha.yaml with the start command it finds in package.json, a Procfile, pyproject.toml or the Dockerfile. When it finds none, pass --agent "<command>".

​
The agent and the tools

ancha init found no start command in your project, so ancha.yaml has none. Set agent.command in ancha.yaml, or pass --agent "<command>".
The agent ran, but no successful call reached that tool. It is probably calling the real service, or not reading the variables Ancha sets. Point its client at the tool URL and credentials from the environment; ancha connect <tool> --lang ts prints the settings. A clean exit or a healthy server does not count as access. The warning does not change doctor’s exit code.
ancha run gives the agent a base set from your shell (PATH, HOME, locale and the like), Ancha’s variables and the tools’ variables, and nothing else. ancha explain says how many variables were withheld. Name the ones the agent needs under agent.pass_env in ancha.yaml, or pass --pass-env NAME for one run. --inherit-env passes everything, as 0.1.1 did, and prints a warning. See ancha run.
Send the credentials the way the real service expects them: Bearer for most tools, Token token= for PagerDuty, DD-API-KEY and DD-APPLICATION-KEY headers for Datadog, HTTP Basic for Gong and Jira, plus LinkedIn-Version and X-Restli-Protocol-Version for LinkedIn Ads. Use the full base URL from the environment; Slack’s ends in /api/. Each tool page has a working snippet, and ancha connect <tool> prints it.
That endpoint is not implemented by the replica. The response carries x-ancha-gap: 1 and a message that starts with ancha: not implemented:, and ancha run and ancha explain list it as a coverage gap. Check ancha twins coverage <tool> for a supported way to do the same thing. Do not rewrite working code to satisfy a replica that lacks an endpoint.

​
Checks

Trace patterns match the method and the path. Paths are relative to the tool’s base URL and exclude the query string. Use * as the method when the HTTP verb does not matter; Slack’s SDKs call every method with POST, while plain fetch code often uses GET. ancha explain lists the calls the agent made.
Read actual in ancha explain. It counts the bot’s messages in the channel and in the thread, which tells you whether the reply went to the wrong thread, the wrong channel or had the wrong text. in_thread_of counts replies only, not the parent message, and text_contains ignores case.
State checks count starter data too. Without from, a message from the starter history can satisfy the check. Set from: $bot, or the ref of the user your agent posts as.
The summary says judge grading skipped with Judge skipped: OPENROUTER_API_KEY is not configured. Export OPENROUTER_API_KEY in the shell that runs ancha run or ancha check. A skipped check never passes, so a required one fails its trial; keep advisory rubrics out of pass.

​
Runs

The agent ran past the scene’s timeout and was stopped. The starter scene allows 10 seconds; the default for new scenes is 5 minutes. Raise timeout in the scene, or make the agent finish. ancha explain shows the end of its log.
Ancha itself failed in at least one trial, so those trials are not counted as agent failures. Read harnessIssues in the summary, fix the cause if it is local (ports, disk, Docker), and run again.
Every required check is compared, not only the scene. A check whose pass rate fell is listed first as dropped, and the run exits 1, even when another check improved and the scene’s rate held. Fix the dropped check, or save a new baseline if the drop is intended.
A comparison needs the same scenes, with the same content and checks, as the baseline. If you changed a scene, save a new baseline. A baseline with invalid trials cannot be used either. Use the same --out for run, baseline and explain if you changed it.
Baselines are never overwritten by accident. Pick another name or pass --force.
An idempotency key belongs to one run definition: the same scenes, agent and options. Reuse a key only to retry the exact same command. Use a new key for a new run.
latest points at the newest completed run in .ancha/runs. If you passed --out to ancha run, pass the same --out to explain, report, logs, status and wait.
Start it with ancha run --detach --json and follow it with ancha logs <run-id> --follow, ancha status <run-id> or ancha wait <run-id>. Stopping logs or wait does not stop the run.

​
Hosted workspace

Running your own agent inside the workspace is in private beta: Bring your agent, Connect agent, and the ancha agent commands that reach the workspace are refused until your workspace has access. The hint says what to do: run ancha run on your computer, where your worlds and results still work, or request access at app.ancha.io/account under Hosted runs. The sample agent and its runs, worlds, sandboxes, scenarios, tools, secrets and runs from your computer against hosted worlds all work.
A workspace has 10 hours of machine time a month, and Settings shows the hours used. When they are used up, the console shows a banner, the workspace keeps your data, and the machine can start again on the 1st of the next month. Until then a call to a world in the workspace answers this workspace's hosted hours for the month are used up. Runs on your computer are not limited, but a run whose worlds are in the workspace starts the machine and uses its hours: pass --local, or unset ANCHA_SERVER_URL and server.url, to keep the worlds on this computer.
The key was revoked, is wrong, or is missing. Run ancha login again, or set a current ANCHA_API_KEY from Settings. ancha whoami --verify tells you whether the server accepts the key you have.
The server cannot be reached: a wrong address, a network problem, or a workspace that is still starting. Check --server-url, server.url and ANCHA_SERVER_URL; ancha whoami shows the server commands use. A sleeping workspace wakes in seconds; retry.
ancha run, ancha doctor and ancha world up put their worlds in the workspace only when --server-url, server.url in ancha.yaml or ANCHA_SERVER_URL names it; a saved login alone keeps the worlds on this computer. The first line of the run says running on hosted … when they went there. Pass --local to keep one command on this computer, or remove the setting; ancha whoami shows which one is in effect.
A workspace sleeps after 30 minutes without traffic and wakes in seconds. The first start takes a few minutes. The page refreshes on its own.
ancha secrets needs a hosted server. Run ancha login, or set ANCHA_SERVER_URL and ANCHA_API_KEY. Export the variable before ancha secrets set NAME; the value comes from your shell.

​
Live worlds and generated worlds

The world’s lease ran out, ancha world down removed it, or its local server stopped. Every ancha world and ancha check command, and every call from the agent, renews the lease (default 30 minutes; set --ttl). Start a new one with ancha world up --json, from the same directory you use for the other commands.
The world started from a saved world (--world <id>), which has no checks. Pass the file whose checks to apply: ancha check --env <id> --test <scene.yaml>.
ancha world up --on cloud puts the world in your hosted workspace, so it needs one: run ancha login, or set ANCHA_SERVER_URL and ANCHA_API_KEY. Without --on, the world goes where ancha run would put it.
ancha world gen calls a model through OpenRouter. Export OPENROUTER_API_KEY in the shell, then run the same command again. See ancha world gen.

​
Playgrounds and containers

ancha execution doctor cannot reach a Docker engine. Start Docker Desktop, OrbStack or Colima, make sure the docker command is on your PATH, or set ANCHA_DOCKER_CONTEXT to the context to use.
Run ancha execution prepare once in the project. It needs Docker with Compose and Python 3.12 or 3.13; set ANCHA_HARBOR_PYTHON to use another interpreter. Run it again after upgrading Ancha when ancha execution doctor --json reports worldImageReady: false.
ancha agent add without --container-image saves a host-process profile. For playground runs, update it with ancha agent update <id> --container-image node:24-slim (or another image with your runtime), then ancha agent prepare <id>.
Google Ads cannot be used in playground runs or with container execution. Remove it from the world, or test it with ancha run as a local process.

​
Still stuck

Email patrick@ancha.io with the command, its output and ancha --version, or book a call. Never include API keys.