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

> Save a reusable agent profile (folder, start command, task input, execution and model provider), prepare and check it, and run it against bundled or workspace scenarios.

An agent profile tells Ancha how to start your agent and hand it a task. Profiles are saved in `.ancha/` and shared by `ancha playground`, `ancha test` and the local console. Every subcommand takes `--json`.

## ancha agent add

```bash theme={null}
ancha agent add [options]
```

| Option | Description |
| - | - |
| `--name <name>` | Agent name |
| `--cwd <folder>` | Local project folder |
| `--command <command>` | Start command |
| `--agent-config <path>` | Existing ancha.yaml, relative to the project |
| `--state <state>` | Stateless, namespaced (uses ANCHA\_STATE\_DIR), or external |
| `--container-image <image>` | Execute in this local Linux image; never fall back to a host process |
| `--host` | Execute directly on this computer without containment |
| `--source <path>` | Relative project path to copy; repeat for more paths (default .) |
| `--pass-env <name>` | Inherit this environment variable by name; repeat for more names |
| `--model-host <domain>` | Permit HTTPS to this exact model-provider domain; repeat for more hosts |
| `--cpus <count>` | Container CPU limit (default 1) |
| `--memory-mb <mb>` | Container memory limit (default 512) |
| `--pids <count>` | Container process limit (default 128) |
| `--task-input <method>` | Unknown, command (ANCHA\_TASK/context), events, or http |
| `--task-path <path>` | HTTP task path (default /api/chat) |
| `--ready-path <path>` | HTTP readiness path (default /ok) |
| `--message-field <field>` | Task request JSON field (default message) |
| `--response-field <field>` | Readable reply JSON field (default reply) |
| `--conversation-path <path>` | Optional POST path to create a conversation before the task |
| `--conversation-id-field <field>` | Conversation response/request field (default conversation\_id) |
| `--startup-timeout <ms>` | HTTP readiness limit in milliseconds (default 60000) |
| `--response-timeout <ms>` | HTTP response limit in milliseconds (defaults to the task time limit) |
| `--provider <provider>` | Model provider (choices: "openrouter", "openai", "anthropic") |
| `--model <id>` | Optional explicit model identifier |
| `--credential-source <source>` | Env or the approved OpenRouter key file (.ancha/openrouter.env) (choices: "env", "file") |

```bash theme={null}
ancha agent add --name "Quickstart agent" --cwd . \
  --command "node agent.mjs" --state stateless --task-input command
```

```text Output theme={null}
Quickstart agent: agent_2817abf5-f4bb-4cf3-9839-77309f18c2fc
Task input: Command task context (ANCHA_TASK)
Execution: Host process · not contained
Check startup with ancha agent verify agent_2817abf5-f4bb-4cf3-9839-77309f18c2fc
```

Without `--container-image`, the profile runs the agent as a host process. Playground runs need a container: add `--container-image node:24-slim` (or another Linux image) and prepare it with `ancha agent prepare`.

### Task input

| `--task-input` | The agent receives the task |
| - | - |
| `command` | In `ANCHA_TASK`. It writes its answer to stdout. |
| `http` | As a JSON POST to `--task-path` (default `/api/chat`) with the text in `--message-field` (default `message`). Ancha waits for `--ready-path` (default `/ok`) and reads the reply from `--response-field` (default `reply`). The agent listens on `0.0.0.0` at `$ANCHA_AGENT_PORT`. |
| `events` | Through the event feed. Not supported in playground runs. |
| `unknown` | Not declared. The process starts, but delivery is not established. |

For a conversation API, `--conversation-path` creates a conversation first and `--conversation-id-field` names its ID field.

### State

| `--state` | Meaning |
| - | - |
| `stateless` | The agent keeps no memory between attempts. |
| `namespaced` | The agent keeps memory under `ANCHA_STATE_DIR`, which is fresh per attempt. |
| `external` | The agent uses memory Ancha cannot isolate. Only one attempt can run. |

### Model provider

`--provider` is `openrouter`, `openai` or `anthropic`, with an optional `--model`. The profile stores a reference, never a key:

* `--credential-source env` reads the provider's standard variable, such as `OPENAI_API_KEY`, from the environment of the CLI.
* `--credential-source file` reads `OPENROUTER_API_KEY=...` from `.ancha/openrouter.env`. OpenRouter only.

`ancha agent inspect <id>` reports whether the key is available, without printing it. Model calls can cost money.

## ancha agent update

```bash theme={null}
ancha agent update [options] <id>
```

| Option | Description |
| - | - |
| `--name <name>` | Agent name |
| `--cwd <folder>` | Project folder |
| `--command <command>` | Start command |
| `--agent-config <path>` | Configuration path |
| `--state <state>` | Stateless, namespaced or external |
| `--container-image <image>` | Execute in this local Linux image; never fall back to a host process |
| `--host` | Execute directly on this computer without containment |
| `--source <path>` | Relative project path to copy; repeat for more paths (default .) |
| `--pass-env <name>` | Inherit this environment variable by name; repeat for more names |
| `--model-host <domain>` | Permit HTTPS to this exact model-provider domain; repeat for more hosts |
| `--cpus <count>` | Container CPU limit (default 1) |
| `--memory-mb <mb>` | Container memory limit (default 512) |
| `--pids <count>` | Container process limit (default 128) |
| `--task-input <method>` | Unknown, command (ANCHA\_TASK/context), events, or http |
| `--task-path <path>` | HTTP task path (default /api/chat) |
| `--ready-path <path>` | HTTP readiness path (default /ok) |
| `--message-field <field>` | Task request JSON field (default message) |
| `--response-field <field>` | Readable reply JSON field (default reply) |
| `--conversation-path <path>` | Optional POST path to create a conversation before the task |
| `--conversation-id-field <field>` | Conversation response/request field (default conversation\_id) |
| `--startup-timeout <ms>` | HTTP readiness limit in milliseconds (default 60000) |
| `--response-timeout <ms>` | HTTP response limit in milliseconds (defaults to the task time limit) |
| `--provider <provider>` | Model provider (choices: "none", "openrouter", "openai", "anthropic") |
| `--model <id>` | Optional explicit model identifier |
| `--credential-source <source>` | Env or the approved OpenRouter key file (.ancha/openrouter.env) (choices: "env", "file") |

Changes any setting while keeping the agent's ID and run history.

## ancha agent list, show, inspect and remove

```bash theme={null}
ancha agent list [options]
```

```text Output theme={null}
agent_2817abf5-f4bb-4cf3-9839-77309f18c2fc  Quickstart agent  unverified  Host process · not contained
```

```bash theme={null}
ancha agent show [options] <id>
```

```bash theme={null}
ancha agent inspect [options] <id>
```

```bash theme={null}
ancha agent remove [options] <id>
```

`remove` deletes the profile and keeps its past results.

## ancha agent detect

```bash theme={null}
ancha agent detect [options]
```

| Option | Description |
| - | - |
| `--cwd <folder>` | Project folder to inspect without running code |

Reads known manifests in a folder, without running code, and suggests settings.

## ancha agent prepare

```bash theme={null}
ancha agent prepare [options] <id>
```

| Argument | Description |
| - | - |
| `id` | Registered agent |

Builds a Linux image of the project with its dependencies, for container runs. It uses a `Dockerfile` in the project, or a supported Node or Python manifest; Node projects need a lockfile. Run it after `add` and again when dependencies change. Needs `ancha execution prepare` first.

## ancha agent connect, connection and cancel-connection

```bash theme={null}
ancha agent connect [options] <agentId>
```

```bash theme={null}
ancha agent connection [options] <agentId>
```

```bash theme={null}
ancha agent cancel-connection [options] <agentId> <operationId>
```

`connect` prepares the agent and checks that it starts, in isolation. A profile whose startup check passed is **Connected**. One with no safe check is **Configured** until a real run shows it working. `connection` shows the progress, and `cancel-connection` stops it.

## ancha agent verify

```bash theme={null}
ancha agent verify [options] <id>
```

| Option | Description |
| - | - |
| `--scene <key...>` | Optional scenario context (default bundled:false-alarm); HTTP checks send no task |
| `-n, --trials <n>` | Attempts per case (default: "1") |
| `--parallel <n>` | Worker limit (default: "1") |
| `--seed <seed>` | Fixed world seed (default: "test-1") |

```text Output theme={null}
run_started runId=run_20261031-075305_b2487967d148f3af
run_20261031-075305_b2487967d148f3af: connected
Ancha started or reached the agent. Tool activity and task outcomes are evaluated separately.
```

Checks that the agent starts and becomes ready, using a bundled scenario's world. It reports tool use and task outcomes separately from startup.

## ancha agent run, rerun, scenarios and scenario

```bash theme={null}
ancha agent run [options] <id>
```

| Option | Description |
| - | - |
| `--scene <key...>` | Catalog keys; list them with ancha agent scenarios |
| `-n, --trials <n>` | Attempts per case (default: "1") |
| `--parallel <n>` | Worker limit (default: "1") |
| `--seed <seed>` | Fixed world seed (default: "test-1") |

```bash theme={null}
ancha agent run agent_2817abf5-f4bb-4cf3-9839-77309f18c2fc --scene workspace:scenes/starter/scene.yaml -n 2
```

```text Output theme={null}
run_started runId=run_20261031-075305_58f8f7611bae17ed
run_20261031-075305_58f8f7611bae17ed: pass
Use ancha report or ancha explain to inspect the result.
```

Runs scenarios from clean worlds, with up to 10 attempts per scenario and 4 workers. Read results with `ancha explain` and `ancha report`, and save the setup with [`ancha test save`](https://docs.ancha.io/cli/test).

```bash theme={null}
ancha agent scenarios [options]
```

```text Output theme={null}
bundled:bad-deploy  Orders requests are failing after a deploy
bundled:db-disk-full  Database writes are failing
bundled:false-alarm  Investigate the transient alert and current customer impact
bundled:flapping-monitor  The telemetry monitor repeatedly pages while customer signals stay healthy
bundled:status-request  Orders requests are failing after a deploy
workspace:scenes/starter/scene.yaml  Discover the four local services
...
```

Keys are `bundled:<name>` for scenarios shipped with the CLI, `compiled:<file>:<name>@<version>` for compiled scenario data, and `workspace:<path>` for scene files in your project.

```bash theme={null}
ancha agent scenario [options] <key>
```

```bash theme={null}
ancha agent rerun [options] <runId>
```

`rerun` repeats a run with the same scenarios and data and your current agent code.


## Related topics

- [ancha.yaml](https://docs.ancha.io/reference/ancha-yaml.md)
- [ancha playground](https://docs.ancha.io/cli/playground.md)
- [ancha test](https://docs.ancha.io/cli/test.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)
- [CLI overview](https://docs.ancha.io/cli/overview.md)


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