Attempts and runs

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

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.

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.

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-<scene>-<n>/agent.log`	Everything the agent printed.
`trial-<scene>-<n>/trace.jsonl`	Every API call in order, with method, path, status and response.
`trial-<scene>-<n>/state.json`	The final state of every tool.
`trial-<scene>-<n>/checks.json`	Each check’s result with expected, actual and the trace entries behind it.
`trial-<scene>-<n>/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 <run> --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 <run-id> --follow, ancha wait <run-id> or ancha status <run-id>. 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.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

Attempts and runs

What each attempt gets

Where the agent runs

Outcomes

Time limits

Parallel attempts

What `ancha run` records

Long runs

​What each attempt gets

​Where the agent runs

​Outcomes

​Time limits

​Parallel attempts

​What ancha run records

​Long runs

What each attempt gets

Where the agent runs

Outcomes

Time limits

Parallel attempts

What `ancha run` records

Long runs