Quickstart

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

Install the CLI

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.

Create a project and an agent

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:

agent.mjs

// 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);
}

Set up the project

ancha init --agent "node agent.mjs"

Output

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 for the full list of files.

Check the setup

ancha doctor

Output

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.

Run the test

ancha run

Output

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

Remove the PagerDuty call

sed -i.bak '/PAGERDUTY/d' agent.mjs
ancha run

Output

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.

Explain the failure

ancha explain latest

Output

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.

Save the failing run as a baseline

ancha baseline save before

Fix the agent and prove the fix

mv agent.mjs.bak agent.mjs
ancha run --compare before

Output

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:

ancha connect slack --lang ts

Output

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. The starter only proves your agent can reach each tool. Replace it with a scene that checks real work. Test a Slack bot walks through one.

Next steps

For coding agents

Hand this loop to Claude Code, Codex or Cursor.

Write a scene

Tools, starter data, a task and checks in one YAML file.

Checks

State, trace and judge checks.

Hosted workspace

Run the same worlds in your private workspace at app.ancha.io.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

Before you start

Run your first test

Break it and read why

Test your own agent

Next steps

For coding agents

Write a scene

Checks

Hosted workspace

​Before you start

​Run your first test

​Break it and read why

​Test your own agent

​Next steps

For coding agents

Write a scene

Checks

Hosted workspace

Before you start

Run your first test

Break it and read why

Test your own agent

Next steps