> ## Documentation Index > Fetch the complete documentation index at: https://docs.ancha.io/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict. # Attempts and runs > A run tries every task of a test several times. Each attempt gets a fresh world and a fresh agent process, and Ancha records everything it did. A run is one execution of a test. It tries each task several times. Each try is an attempt. `ancha run` output calls an attempt a trial. Running the same task many times tells you how reliable the agent is. An agent that passes 3 of 5 attempts has a problem that a single run can hide. ## What each attempt gets | Fresh per attempt | Detail | | - | - | | World | Its own copy of the tools, built from the same seed. Writes in one attempt never appear in another. | | Tool addresses and credentials | Its own URLs and fake credentials, passed in environment variables. See [Environment variables](https://docs.ancha.io/reference/environment-variables.md). | | Agent process | Ancha starts the agent for the attempt and stops it at the end. | | State directory | `ANCHA_STATE_DIR` points to an empty directory for the agent's own files and memory. | The seed and starting data stay the same across attempts, so every attempt starts from the same state. ## Where the agent runs | You start the run with | The agent runs | Isolation | | - | - | - | | `ancha run` | As an ordinary process on your computer, in the project directory, with a base set of your shell's variables, the names you allow in `agent.pass_env`, and Ancha's variables | Tool state is separate per attempt. The process itself is not sealed: it shares your files and network. Your shell's other variables, such as real credentials, are withheld unless you pass them. See [`ancha run`](https://docs.ancha.io/cli/run#what-the-agent-gets). | | `ancha run` with `agent.execution.mode: container` | In a local Linux container from an image you provide | Read-only source without Ancha's own files, only the environment variables you list, no network except the tools and the model hosts you allow. See [ancha.yaml](https://docs.ancha.io/reference/ancha-yaml.md#agent-execution). | | Your own harness, after `ancha world up` | Wherever your harness starts it | Your harness decides. The agent gets the world's tool variables and nothing that controls the world. `ancha check` grades the result. See [World lifecycle](https://docs.ancha.io/cli/world-lifecycle.md). | | `ancha playground start` | In a local container built from your project | A private network per attempt with its own tools. Needs Docker. See [`ancha playground`](https://docs.ancha.io/cli/playground). | | **Run tasks** in the hosted console | In a container in your hosted workspace | Reaches the tools and the model provider you chose, nothing else. See [Hosted workspace](https://docs.ancha.io/cloud/overview.md). | The worlds themselves run on a server `ancha run` starts, or in your hosted workspace after `ancha login`. The first line of every run says which, and the run's JSON carries `workspace` and `target`. See [CLI overview](https://docs.ancha.io/cli/overview.md#which-server-a-command-uses). ## Outcomes | Outcome | Meaning | | - | - | | Passed | Every required check passed. | | Failed | At least one required check failed. | | Agent issue | The agent crashed, exited with an error or ran past the time limit. Its checks are still evaluated against what it did. | | Invalid | Ancha itself failed during the attempt. The attempt does not count as an agent failure, and the run exits with code `3`. | | Ungraded | Its task has no checks, so the attempt finished without a verdict. | Coverage gaps are reported alongside the outcome. A gap means the agent called an endpoint the replica does not implement. It does not fail the attempt unless you pass `--strict`. ## Time limits Each attempt has a time limit: `timeout` in a scene file (default `5m`), or `timeoutMs` on a playground task (default 300,000 ms). When it runs out, Ancha stops the agent and records a timeout. `ancha doctor` uses a 10-second limit by default. Results report both real time (`realMs`) and simulated time (`simMs`). See [Worlds](https://docs.ancha.io/concepts/worlds.md#time). ## Parallel attempts `parallel` in `ancha.yaml`, or `--parallel`, sets how many trials of `ancha run` run at once. The default is 2 for command agents and 1 for HTTP endpoint agents. Playground runs use `--concurrency` (at most 10). The local container runtime admits at most three attempts of one run at a time and can run fewer when the machine is busy. ## What `ancha run` records Each run gets a directory under `.ancha/runs/`, named by its run ID, for example `run_20261031-071656_195dc8894e8b58a1`. | Path | Contents | | - | - | | `summary.json` | The run's summary: verdict, pass rates, check tallies, failures, issues, coverage gaps, where the worlds ran and what the agent's environment held. | | `inputs.json` | The exact scenes and seeds the run used, and how the agent was executed. | | `trial--/agent.log` | Everything the agent printed. | | `trial--/trace.jsonl` | Every API call in order, with method, path, status and response. | | `trial--/state.json` | The final state of every tool. | | `trial--/checks.json` | Each check's result with expected, actual and the trace entries behind it. | | `trial--/result.json` | The trial's outcome, exit code and timings. | | `.ancha/runs/latest` | The ID of the most recent completed run. Commands accept `latest` in place of a run ID. | `ancha explain`, `ancha report`, `ancha logs` and `ancha run --compare` read these files. `ancha report --html` writes a self-contained `report.html` into the run's directory. ## Long runs `ancha run --detach` keeps the run going in a background worker after the command returns. Follow it with `ancha logs --follow`, `ancha wait ` or `ancha status `. `logs --follow` and `wait` exit with the run's original exit code. A command that may time out can pass `--idempotency-key` so a retry returns the same run. See [`ancha run`](https://docs.ancha.io/cli/run#detached-runs). ## Related topics - [Hosted workspace](https://docs.ancha.io/cloud/overview.md) - [How Ancha works](https://docs.ancha.io/concepts/overview.md) - [ancha run](https://docs.ancha.io/cli/run.md) - [Checks reference](https://docs.ancha.io/reference/checks.md) - [ancha runs](https://docs.ancha.io/cli/runs.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.