ancha agent

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

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”)

ancha agent add --name "Quickstart agent" --cwd . \
  --command "node agent.mjs" --state stateless --task-input command

Output

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

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

ancha agent list [options]

Output

agent_2817abf5-f4bb-4cf3-9839-77309f18c2fc  Quickstart agent  unverified  Host process · not contained

ancha agent show [options] <id>

ancha agent inspect [options] <id>

ancha agent remove [options] <id>

remove deletes the profile and keeps its past results.

ancha agent detect

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

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

ancha agent connect [options] <agentId>

ancha agent connection [options] <agentId>

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

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”)

Output

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

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”)

ancha agent run agent_2817abf5-f4bb-4cf3-9839-77309f18c2fc --scene workspace:scenes/starter/scene.yaml -n 2

Output

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.

ancha agent scenarios [options]

Output

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.

ancha agent scenario [options] <key>

ancha agent rerun [options] <runId>

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

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

ancha agent add

Task input

State

Model provider

ancha agent update

ancha agent list, show, inspect and remove

ancha agent detect

ancha agent prepare

ancha agent connect, connection and cancel-connection

ancha agent verify

ancha agent run, rerun, scenarios and scenario

​ancha agent add

​Task input

​State

​Model provider

​ancha agent update

​ancha agent list, show, inspect and remove

​ancha agent detect

​ancha agent prepare

​ancha agent connect, connection and cancel-connection

​ancha agent verify

​ancha agent run, rerun, scenarios and scenario

ancha agent add

Task input

State

Model provider

ancha agent update

ancha agent list, show, inspect and remove

ancha agent detect

ancha agent prepare

ancha agent connect, connection and cancel-connection

ancha agent verify

ancha agent run, rerun, scenarios and scenario