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

# ancha.yaml

> Every field of ancha.yaml, the config file for ancha run and ancha doctor: the agent and how it starts, which variables it inherits, scenes, trials, parallelism, pass rate, server and judge model.

`ancha.yaml` configures `ancha run` and `ancha doctor`. `ancha init` writes one. The CLI reads `ancha.yaml` in the current directory, or the file passed with `--config`. Without a file, the defaults below apply. `ancha schema ancha` prints the JSON Schema.

```yaml ancha.yaml theme={null}
agent:
  command: node agent.mjs
  pass_env: [OPENAI_API_KEY]
scenes: [scenes/**/scene.yaml]
trials: 5
parallel: 2
min_pass_rate: 0.8
```

Paths in the file, including `scenes` globs and `agent.cwd`, are relative to the directory you run the CLI from, even when `--config` points elsewhere.

## Top-level fields

| Field | Type | Default | Meaning |
| - | - | - | - |
| `agent` | mapping | none | How to start the agent. See below. `--agent` on the command line overrides `agent.command`. |
| `scenes` | list of globs | `[scenes/**/scene.yaml]` | Scene files to run. |
| `trials` | positive integer | `5` | Trials per scene. `-n` overrides it. `ancha init` writes `1`. |
| `parallel` | positive integer | `2` for command agents, `1` for endpoint agents | Trials running at once. `--parallel` overrides it. |
| `min_pass_rate` | number, 0 to 1 | `1` | Fraction of each scene's trials that must pass. `--min-pass-rate` overrides it. |
| `server.url` | http(s) URL | none | Use this Ancha server instead of starting one. |
| `judge.model` | string | | OpenRouter model for judge checks. |

Unknown fields are errors. See [Validation](#validation).

## Command agents

A command agent is a process Ancha starts for each trial. It gets the task and tool variables in its environment and is done when it exits.

| Field | Type | Meaning |
| - | - | - |
| `agent.command` | string | Shell command that starts the agent, for example `node agent.mjs` or `python -m agent`. |
| `agent.cwd` | string | Directory to start it in. Default: the current directory. |
| `agent.env` | mapping | Extra environment variables. Values are strings and may use [templates](#templates). Quote numbers: `PORT: "8080"`. |
| `agent.pass_env` | list of names | Variables the agent inherits from your shell besides the base set. Names only; values come from the shell at run time and are never saved. `--pass-env NAME` adds one for a run. |
| `agent.input` | `command` or `per_event` | `command` (default) runs the agent once per attempt with the task in `ANCHA_TASK`. `per_event` runs it once per event addressed to it, such as a message from a person in the world, with the event in `ANCHA_EVENT_JSON` and a one-line summary in `ANCHA_TASK`. |
| `agent.slack_transport` | `feed`, `http` or `socket` | How Slack events reach the agent. Default `feed`. See [Slack](https://docs.ancha.io/tools/slack.md#events). |
| `agent.execution` | mapping | Run the agent in a container instead of as a local process. See [Agent execution](#agent-execution). |

The agent process starts with a base set of variables from your shell (`PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `LANG`, `LC_*`, `TERM`, `TMPDIR`, `TZ`, `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `VIRTUAL_ENV`, `CONDA_PREFIX`, `PYTHONPATH`), the names in `agent.pass_env`, the variables in [Environment variables](https://docs.ancha.io/reference/environment-variables.md) and `agent.env`. Entries in `agent.env` win. Nothing else from your shell reaches it, unless you run with `--inherit-env`. See [`ancha run`](https://docs.ancha.io/cli/run#what-the-agent-gets).

## Endpoint agents

An endpoint agent is an HTTP server that receives events. Setting `agent.url` selects this mode; it cannot be combined with `agent.command`.

```yaml theme={null}
agent:
  url: "http://127.0.0.1:{{agent.port}}/events/{{service}}"
  start: node server.mjs
  ready_url: "http://127.0.0.1:{{agent.port}}/ready"
  idle: 10s
  startup_timeout: 30s
parallel: 2
```

| Field | Type | Default | Meaning |
| - | - | - | - |
| `agent.url` | URL template | | Where Ancha delivers events. `{{service}}` becomes `slack`, `github`, `datadog` or `pagerduty`. |
| `agent.start` | string | | Command that starts the server for each trial. It must listen on `$ANCHA_AGENT_PORT`. |
| `agent.ready_url` | URL template | | Ancha polls it with GET until it returns 2xx. Required with `start`. A managed server must also return the header `x-ancha-env-id` with the value of `ANCHA_ENV_ID`. |
| `agent.setup_url` | URL template | | For a server you run yourself: Ancha POSTs the trial's environment, session and task here once per trial. Conflicts with `start`. |
| `agent.idle` | duration | `10s` | The trial ends after this much quiet simulated time with no pending work. |
| `agent.startup_timeout` | duration | `30s` | Time allowed for start, readiness and Slack URL verification. |

`parallel` above 1 needs `start` and `{{agent.port}}` in both `url` and `ready_url`, so each trial gets its own server on a loopback address. Endpoint agents cannot use `slack_transport: socket`. To end a trial early, POST `{}` to `ANCHA_DONE_URL` with `Authorization: Bearer <ANCHA_TRIAL_TOKEN>`.

## Templates

Values in `agent.env` and the endpoint URLs may contain `{{name}}` placeholders. An unknown name is an error whose hint lists the available ones.

| Placeholder | Value |
| - | - |
| `{{task}}`, `{{trial}}`, `{{env.id}}` | The scene's task, the trial number and the environment ID. |
| `{{<tool>.url}}`, `{{<tool>.token}}` | A tool's base URL and token, for example `{{slack.url}}`. |
| `{{<tool>.signing_secret}}` | A tool's webhook signing secret. |
| `{{slack.app_token}}` | Slack's app token. |
| `{{datadog.api_key}}`, `{{datadog.app_key}}`, `{{datadog.webhook_token}}` | Datadog credentials. |
| `{{pagerduty.from_email}}`, `{{pagerduty.routing_key}}`, `{{pagerduty.routing_keys}}` | PagerDuty identity and routing keys. |
| `{{events.url}}`, `{{events.token}}`, `{{done.url}}`, `{{trial.token}}`, `{{context.url}}` | The trial's event feed, completion and context endpoints and their token. |
| `{{agent.port}}` | The port an endpoint agent listens on. |
| `{{service}}` | In `agent.url` only: the tool an event comes from. |

```yaml theme={null}
agent:
  command: python -m support_bot
  env:
    BOT_SLACK_BASE: "{{slack.url}}"
    BOT_SLACK_TOKEN: "{{slack.token}}"
```

## Agent execution

`agent.execution` decides where the agent process runs.

```yaml theme={null}
agent:
  command: node agent.mjs
  execution:
    mode: container
    image: my-agent:local
    files: [agent.mjs, src]
    modelHosts: [openrouter.ai]
    env: [OPENROUTER_API_KEY]
```

| Field | Default | Meaning |
| - | - | - |
| `mode` | `host` | `host` runs the agent as a local process. `container` runs it in a local Linux container. |
| `image` | | Required for `container`. A Linux image already in your local Docker, with the agent's runtime and dependencies. Images are never pulled during a trial. |
| `preparation` | | `project` rebuilds the image from the project when its build inputs change. `image` uses the image as it is. |
| `files` | `[.]` | Project paths to copy in, read-only, at `/workspace`. Dotfiles, `.env`, VCS and dependency folders, common credential files and Ancha's own files (`ancha.yaml`, `ancha/`, scene folders and the run's scene files) are left out, so the agent cannot read the checks it is graded by. Up to 5,000 files and 512 MiB. |
| `env` | `[]` | Names of variables to pass from your shell. Values are never saved. Reserved names such as `PATH`, `HOME` and `ANCHA_*` are rejected. |
| `modelHosts` | `[]` | Exact domains the agent may reach over HTTPS, such as `openrouter.ai`. Nothing else on the internet is reachable. |
| `cpus` | `1` | 0.1 to 32. |
| `memoryMb` | `512` | 128 to 65536. |
| `pids` | `128` | 16 to 4096. |

In a container, the agent runs as a non-root user with a read-only root, no host folders and no Docker socket. `ANCHA_STATE_DIR` is `/state`. For Node agents, install the dependencies at `/opt/ancha/node_modules` in the image; each trial links them into `/workspace`:

```dockerfile theme={null}
FROM node:24-slim
WORKDIR /opt/ancha
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
WORKDIR /workspace
```

Container runs never fall back to a host process: if Docker or the image is missing, the run stops with an error. They need a local Docker engine (see [`ancha execution`](https://docs.ancha.io/cli/execution)), and do not support Slack Socket Mode or Google Ads.

The agent must use the base URLs it is given. For allowed providers, Ancha sets `OPENROUTER_BASE_URL` (and `OPENAI_BASE_URL` if unset) or the matching OpenAI and Anthropic base URLs to a local gateway, and `ANCHA_MODEL_URLS` maps each allowed domain for other clients.

## Validation

Every problem is reported at once, with its path and a hint, and the command exits `2`:

```text Output theme={null}
error[CONFIG_INVALID]: execution: unknown field
  agent.bogus: unknown field
  trials: expected a positive integer, got 0
hint: execution: did you mean agent.execution? Put it under agent:
  agent.bogus: known fields of agent: command, cwd, env, pass_env, input, slack_transport, execution, url, start, ready_url, setup_url, idle, startup_timeout
  fix the config file: /path/to/project/bad.yaml
```

Durations use units: `500ms`, `10s`, `1m30s`.


## Related topics

- [ancha run](https://docs.ancha.io/cli/run.md)
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)
- [Troubleshooting](https://docs.ancha.io/troubleshooting.md)
- [ancha init](https://docs.ancha.io/cli/init.md)
- [Tests](https://docs.ancha.io/concepts/tests.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.