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

> Run tasks against a saved agent and world in fresh local containers, one per attempt, then inspect, compare, stop and rerun the attempts. Includes saved playground tests and multi-agent groups.

`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:

1. Docker with Compose, Python 3.12 or later and Node.js 24 or later.
2. `ancha execution prepare` to install the local runtime. See [`ancha execution`](https://docs.ancha.io/cli/execution).
3. A container agent: `ancha agent add ... --container-image <image>`, then `ancha agent prepare <id>`. See [`ancha agent`](https://docs.ancha.io/cli/agent).
4. A world: `ancha world create --name ... --tools ...`. See [`ancha world`](https://docs.ancha.io/cli/world).

Check before spending model tokens:

```bash theme={null}
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

```bash theme={null}
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") |

```bash theme={null}
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:

```json tasks.json theme={null}
[
  {
    "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](https://docs.ancha.io/reference/checks.md). |

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

```bash theme={null}
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") |

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

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

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

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

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

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

```bash theme={null}
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

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

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

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

| Argument | Description |
| - | - |
| `id` | Playground run id |

```bash theme={null}
ancha playground attempt [options] <id> <attempt-id>
```

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

```bash theme={null}
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.

```bash theme={null}
ancha playground wait [options] <id>
```

| Argument | Description |
| - | - |
| `id` | Playground run id |

```bash theme={null}
ancha playground stop [options] <id>
```

| Argument | Description |
| - | - |
| `id` | Playground run id |

```bash theme={null}
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

```bash theme={null}
ancha playground group start [options]
```

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

```json group.json theme={null}
{
  "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](https://docs.ancha.io/reference/environment-variables.md). |
| `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

```bash theme={null}
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 |

```bash theme={null}
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>`.


## Related topics

- [ancha test](https://docs.ancha.io/cli/test.md)
- [ancha execution](https://docs.ancha.io/cli/execution.md)
- [ancha agent](https://docs.ancha.io/cli/agent.md)
- [How Ancha works](https://docs.ancha.io/concepts/overview.md)
- [Tests](https://docs.ancha.io/concepts/tests.md)


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