ancha.yaml

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.

ancha.yaml

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.

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. 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.
`agent.execution`	mapping	Run the agent in a container instead of as a local process. See 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 and agent.env. Entries in agent.env win. Nothing else from your shell reaches it, unless you run with --inherit-env. See ancha run.

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.

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.

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.

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:

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), 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:

Output

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.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

Top-level fields

Command agents

Endpoint agents

Templates

Agent execution

Validation

​Top-level fields

​Command agents

​Endpoint agents

​Templates

​Agent execution

​Validation

Top-level fields

Command agents

Endpoint agents

Templates

Agent execution

Validation