ancha playground

ancha playground runs your agent the way the hosted console does: each attempt gets its own container for the agent and its own copy of the tools on a private network. Tasks are plain-language prompts; attempts with checks are graded.

Before you start

Playground runs need, once per project:

Docker with Compose, Python 3.12 or later and Node.js 24 or later.
ancha execution prepare to install the local runtime. See ancha execution.
A container agent: ancha agent add ... --container-image <image>, then ancha agent prepare <id>. See ancha agent.
A world: ancha world create --name ... --tools .... See ancha world.

Check before spending model tokens:

ancha playground readiness [options]

Option	Description
`--agent <id>`	Registered agent
`--world <id>`	Selected world
`--world-revision <number>`	Pinned world revision
`--test <id>`	Saved test

Without the runtime, it exits 2 with Set up the local execution runtime before starting a playground.

Run tasks

ancha playground start [options]

Option	Description
`--agent <id>`	Registered agent
`--world <id>`	Selected world
`--world-revision <number>`	Pinned world revision
`--test <id>`	Saved test
`--task <prompt>`	One task in plain English
`--tasks <file>`	JSON or YAML array of tasks, each with prompt, attempts and optional title/timeoutMs
`--idempotency-key <key>`	Reuse the same submission when retrying an uncertain start
`--attempts <count>`	Repetitions for —task (default: “1”)
`--timeout <ms>`	Execution time limit for —task (default: “300000”)
`--concurrency <count>`	Maximum attempts running together (default: “1”)
`--seed <seed>`	Reproducible world seed (default: “playground-1”)

ancha playground start --agent <agent-id> --world <world-id> \
  --task "Answer the newest question in Slack #support in its thread." \
  --attempts 5 --concurrency 2 --json

Use --tasks tasks.json for several tasks, or --test <test-id> for a saved test. start stays in the foreground and prints the run ID and the results. Ctrl-C stops the run and keeps what was captured. tasks.json is an array:

tasks.json

[
  {
    "title": "Answer the newest support question",
    "prompt": "Answer the newest unanswered question in Slack #support in its thread.",
    "attempts": 3,
    "timeoutMs": 120000,
    "checks": [
      {"id": "replied", "state": {"slack.message": {"channel": "$slack_support", "from": "$slack_bot", "in_thread_of": "$slack_question"}}}
    ]
  }
]

Field	Rule
`prompt`	Required. Up to 20,000 characters.
`attempts`	Required. At least 1; at most 100 across all tasks of a run.
`title`	Optional, up to 120 characters. Defaults to the prompt’s first line.
`timeoutMs`	Optional, 1,000 to 3,600,000. Default 300,000.
`checks`	Optional `state` and `trace` checks, up to 20. Without them, attempts are ungraded. See Checks reference.

A run holds up to 20 tasks. --concurrency allows up to 10 attempts at once; the local runtime admits at most three attempts of a run at a time and may run fewer.

Retrying safely

Give --idempotency-key a value you choose. If a start’s response is lost, repeat the same command with the same key to get the original run instead of starting a second, paid one. Reusing a key with different input is rejected.

Saved tests

ancha playground test create [options]

Option	Description
`--name <name>`	Test name
`--agent <id>`	Registered agent
`--world <id>`	World id
`--world-revision <number>`	World revision; defaults to latest
`--tasks <file>`	Task array JSON or YAML
`--concurrency <number>`	Parallel attempts (default: “1”)
`--seed <seed>`	World seed (default: “playground-1”)

ancha playground test list [options]

Option	Description
`--agent <id>`	Filter by agent
`--include-archived`	Include archived tests

ancha playground test show [options] <id>

Option	Description
`--revision <number>`	Historical revision

ancha playground test update [options] <id>

Option	Description
`--definition <file>`	Test definition or patch
`--revision <number>`	Revision being edited

ancha playground test archive [options] <id>

Option	Description
`--revision <number>`	Revision being archived

A test pins the agent, the world revision, the tasks and the concurrency. Start it with ancha playground start --test <test-id>. Updates create a revision and need the current --revision.

Inspect runs

ancha playground list [options]

Option	Description
`--agent <id>`	Filter by agent

ancha playground show [options] <id>

Argument	Description
`id`	Playground run id

ancha playground attempt [options] <id> <attempt-id>

Argument	Description
`id`	Playground run id
`attempt-id`	Attempt id

ancha playground compare [options] <run-id> <left-attempt-id> <right-attempt-id>

show groups attempts by task and gives their IDs. attempt prints the agent’s response, its tool activity and the final tool data. compare puts two attempts of the same task side by side.

ancha playground wait [options] <id>

Argument	Description
`id`	Playground run id

ancha playground stop [options] <id>

Argument	Description
`id`	Playground run id

ancha playground rerun [options] <id>

Argument	Description
`id`	Previous playground run id

Option	Description
`--idempotency-key <key>`	Reuse the same rerun after an uncertain response

rerun repeats the original tasks and pinned data with your current agent code.

Compare agents

ancha playground group start [options]

Option	Description
`--definition <file>`	Group entries JSON or YAML
`--idempotency-key <key>`	Reuse the original submission on retry

group.json

{
  "name": "Support agent comparison",
  "concurrency": 3,
  "entries": [
    {"agentId": "agent_one", "worldId": "world_support", "worldRevision": 1, "seed": "support-1", "tasks": [{"prompt": "Find the latest customer message and draft a reply.", "attempts": 2, "timeoutMs": 30000}]},
    {"agentId": "agent_two", "worldId": "world_support", "worldRevision": 1, "seed": "support-1", "tasks": [{"prompt": "Find the latest customer message and draft a reply.", "attempts": 2, "timeoutMs": 30000}]}
  ]
}

A group holds up to 10 entries and 100 attempts. The inspection commands above work on group runs too.

Inside an attempt

The agent gets	Detail
`ANCHA_TASK`, `ANCHA_ATTEMPT_ID`	The task and the attempt’s ID.
Tool variables	URLs and fake credentials for the world’s tools. See Environment variables.
`ANCHA_CONNECTION_MANIFEST`	Path to a JSON file describing the attempt’s tools, for agents that register tools from it.
`SLACK_MCP_URL`, `ANCHA_MCP_URL`	A Slack MCP endpoint, when the world has Slack.
`ANCHA_STATE_DIR`	A fresh directory for memory.
`ANCHA_AGENT_PORT`	The port an HTTP agent listens on.

The container’s root is read-only. The project is copied into a writable, temporary /workspace. The agent cannot reach host folders, the Docker socket, other attempts or the internet, except the model provider hosts its profile allows. Nothing falls back to running on the host. Event task input, Slack Socket Mode and Google Ads are not supported in playground runs.

Legacy configuration

ancha playground configure [options]

Option	Description
`--agent <id>`	Registered agent
`--tools <names>`	Comma-separated tool names
`--definition <file>`	Pinned configuration JSON or YAML
`--name <name>`	Configuration name

ancha playground configuration [options]

Option	Description
`--agent <id>`	Registered agent

These keep older agent-keyed tool configurations working. Use worlds for new work.

Exit codes

Code	Meaning
`0`	The run completed. Completed does not mean the tasks were done correctly; read the attempts.
`2`	Stopped, not ready, or invalid input.
`3`	Execution error.

Run IDs look like play_<uuid> and attempt IDs like attempt_<uuid>.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

ancha playground

Before you start

Run tasks

Retrying safely

Saved tests

Inspect runs

Compare agents

Inside an attempt

Legacy configuration

Exit codes

​Before you start

​Run tasks

​Retrying safely

​Saved tests

​Inspect runs

​Compare agents

​Inside an attempt

​Legacy configuration

​Exit codes

Before you start

Run tasks

Retrying safely

Saved tests

Inspect runs

Compare agents

Inside an attempt

Legacy configuration

Exit codes