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

# Quickstart

> Install the Ancha CLI, run a small agent against four replicated tools, break it, read why it failed and prove the fix.

You write a 12-line agent, run it against replicas of Slack, GitHub, Datadog and PagerDuty, then break it on purpose and read how Ancha explains the failure. It takes about five minutes and needs no account and no API keys.

## Before you start

* Node.js 24 or later, with npm. Check with `node --version`.
* macOS or Linux.

## Run your first test

**1. Install the CLI**

```bash theme={null}
npm install -g @ancha-labs/cli
ancha --version
```

The second command prints `0.1.4`. To try Ancha without installing it, replace `ancha` with `npx -y @ancha-labs/cli@0.1.4` in every command on this page.

**2. Create a project and an agent**

```bash theme={null}
mkdir ancha-quickstart && cd ancha-quickstart
```

Save this as `agent.mjs`. It reads one thing from each tool with the URLs and fake credentials Ancha puts in its environment:

```js agent.mjs theme={null}
// A minimal agent: read one thing from each tool Ancha provides.
const env = process.env;
const calls = [
  [env.SLACK_API_URL, 'conversations.list', { Authorization: `Bearer ${env.SLACK_BOT_TOKEN}` }],
  [env.GITHUB_API_URL, 'repos/acme/starter', { Authorization: `Bearer ${env.GITHUB_TOKEN}` }],
  [env.DATADOG_API_URL, 'api/v1/dashboard', { 'DD-API-KEY': env.DD_API_KEY, 'DD-APPLICATION-KEY': env.DD_APP_KEY }],
  [env.PAGERDUTY_API_URL, 'services', { Authorization: `Token token=${env.PAGERDUTY_API_TOKEN}` }],
];
for (const [base, path, headers] of calls) {
  const res = await fetch(`${base.replace(/\/+$/, '')}/${path}`, { headers });
  console.log(res.status, path);
}
```

**3. Set up the project**

```bash theme={null}
ancha init --agent "node agent.mjs"
```

```text Output wrap theme={null}
Created 7 files; updated 0; preserved 0.
agent: node agent.mjs
starter: Slack, GitHub, Datadog, PagerDuty (no tool SDK recognized in the dependencies)
next: ancha run
```

`init` writes `ancha.yaml`, a starter scene in `scenes/starter/`, instructions for coding agents and `.ancha/` in `.gitignore`. It installs nothing and runs nothing. With a `package.json` that has a `start` script, you can leave out `--agent`. See [`ancha init`](https://docs.ancha.io/cli/init) for the full list of files.

**4. Check the setup**

```bash theme={null}
ancha doctor
```

```text Output wrap theme={null}
pass  workspace: running locally (worlds in a server this command starts)
pass  node: Node 24.22.2; ancha 0.1.4
pass  config: Configuration is valid
pass  scenes: 1 scenes are valid
pass  runtime: Backend accepted every scene and released its diagnostic environments
pass  agent: Agent completed a bounded diagnostic trial (exited)
pass  native:slack: Observed a successful native slack API request from the configured agent
pass  native:github: Observed a successful native github API request from the configured agent
pass  native:datadog: Observed a successful native datadog API request from the configured agent
pass  native:pagerduty: Observed a successful native pagerduty API request from the configured agent
pass  business: Diagnostic scene checks passed
next: ancha run
```

`doctor` runs your agent once and confirms it reached each tool.

**5. Run the test**

```bash theme={null}
ancha run
```

```text Output wrap theme={null}
running locally (worlds in a server this command starts)
run_started runId=run_20261031-234205_e9f7049f942a39d5 scenes=["starter"] trials=1 parallel=1 workspace=local:/path/to/ancha-quickstart target=local
trial_started scene=starter trial=1 envId=0ykgpn5i
trial_finished scene=starter trial=1 passed=true valid=true warnings=[] exit=exited exitCode=0 realMs=79 failedChecks=[]

✓ starter  1/1 (100%)

agent not sealed: network open; environment limited to 9 variables from this shell (pass more with --pass-env NAME)
pass (minimum pass rate 100%)  run run_20261031-234205_e9f7049f942a39d5
next: ancha baseline save before
```

The command exits with code `0`. The first line says where the worlds ran, here on a server the command started. The starter scene has four checks, one per tool, and each requires a call to that tool. The environment line says the agent got Ancha's variables plus a small base set from your shell, and nothing else.

## Break it and read why

**1. Remove the PagerDuty call**

```bash theme={null}
sed -i.bak '/PAGERDUTY/d' agent.mjs
ancha run
```

```text Output wrap theme={null}
running locally (worlds in a server this command starts)
run_started runId=run_20261031-234205_7570556079db03cd scenes=["starter"] trials=1 parallel=1 workspace=local:/path/to/ancha-quickstart target=local
trial_started scene=starter trial=1 envId=bfktffua
trial_finished scene=starter trial=1 passed=false valid=true warnings=[] exit=exited exitCode=0 realMs=76 failedChecks=["pagerduty_access"]

✗ starter  0/1 (0%)
    ✗ pagerduty_access  failed in 1/1 trials
      trial 1: The agent never made a call matching "* /services*". Its calls were: GET /api/conversations.list, GET /repos/acme/starter, GET /api/v1/dashboard.

agent not sealed: network open; environment limited to 9 variables from this shell (pass more with --pass-env NAME)
fail (minimum pass rate 100%)  run run_20261031-234205_7570556079db03cd
next: ancha explain run_20261031-234205_7570556079db03cd
Patterns are "<METHOD> <PATH>" matched against the service-relative path, and * is a wildcard.
```

The command exits with code `1`: a check failed.

**2. Explain the failure**

```bash theme={null}
ancha explain latest
```

```text Output wrap theme={null}
starter  trial 1  ✗ pagerduty_access
  expected: agent calls * /services*
  actual:   never called; agent made 3 call(s)
  why:      The agent never made a call matching "* /services*". Its calls were: GET /api/conversations.list, GET /repos/acme/starter, GET /api/v1/dashboard.
  trace:
    #1 agent GET /api/conversations.list -> 200
    #2 agent GET /repos/acme/starter -> 200
    #3 agent GET /api/v1/dashboard -> 200

environment: 72 variables from this shell were withheld from the agent. If it needs one (a provider key, say), pass it with --pass-env NAME or list it under agent.pass_env in ancha.yaml.

Patterns are "<METHOD> <PATH>" matched against the service-relative path, and * is a wildcard.

next: ancha baseline save before --from run_20261031-234205_7570556079db03cd, then fix the agent, then ancha run --compare before
```

Each failed check shows what was expected, what happened and the calls the agent made, in order. The `next` line gives the commands that follow.

**3. Save the failing run as a baseline**

```bash theme={null}
ancha baseline save before
```

**4. Fix the agent and prove the fix**

```bash theme={null}
mv agent.mjs.bak agent.mjs
ancha run --compare before
```

```text Output wrap theme={null}
running locally (worlds in a server this command starts)
run_started runId=run_20261031-234206_09b422aebb589f2b scenes=["starter"] trials=1 parallel=1 workspace=local:/path/to/ancha-quickstart target=local
trial_started scene=starter trial=1 envId=qbw16ffq
trial_finished scene=starter trial=1 passed=true valid=true warnings=[] exit=exited exitCode=0 realMs=77 failedChecks=[]

✓ starter  1/1 (100%)

compared with run_20261031-234205_7570556079db03cd: no regression
  starter: 0% → 100% (+100 pp); 1 → 1 trials
    improved: pagerduty_access  0/1 → 1/1
agent not sealed: network open; environment limited to 9 variables from this shell (pass more with --pass-env NAME)
pass (minimum pass rate 100%)  run run_20261031-234206_09b422aebb589f2b
```

Exit code `0` means every check passed and no scene and no check got worse than the baseline.

## Test your own agent

Point `agent.command` in `ancha.yaml` at the command that starts your agent, or let `ancha init` take it from your `package.json`, Procfile, `pyproject.toml` or Dockerfile. Your agent must read tool addresses and credentials from the environment variables Ancha sets. `ancha connect <tool>` prints the SDK settings for a tool:

```bash theme={null}
ancha connect slack --lang ts
```

```text Output wrap theme={null}
Ancha supplies SLACK_API_URL, SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET, SLACK_APP_TOKEN for the selected sandbox or trial.

import { WebClient } from '@slack/web-api';
const slack = new WebClient(process.env.SLACK_BOT_TOKEN, { slackApiUrl: process.env.SLACK_API_URL });
await slack.conversations.list();
```

If your agent needs a key from your shell, such as `OPENAI_API_KEY`, list its name under `agent.pass_env` in `ancha.yaml`. Apart from a base set such as `PATH` and `HOME`, Ancha withholds the rest of your shell from the agent. See [`ancha run`](https://docs.ancha.io/cli/run#what-the-agent-gets).

The starter only proves your agent can reach each tool. Replace it with a scene that checks real work. [Test a Slack bot](https://docs.ancha.io/guides/test-a-slack-bot.md) walks through one.

## Next steps

> [card] [For coding agents](https://docs.ancha.io/coding-agents.md)
>
> Hand this loop to Claude Code, Codex or Cursor.

> [card] [Write a scene](https://docs.ancha.io/reference/test-file.md)
>
> Tools, starter data, a task and checks in one YAML file.

> [card] [Checks](https://docs.ancha.io/concepts/checks.md)
>
> State, trace and judge checks.

> [card] [Hosted workspace](https://docs.ancha.io/cloud/overview.md)
>
> Run the same worlds in your private workspace at app.ancha.io.


## Related topics

- [Test a Slack bot](https://docs.ancha.io/guides/test-a-slack-bot.md)
- [ancha docs](https://docs.ancha.io/cli/docs.md)
- [Introduction](https://docs.ancha.io/index.md)


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