World lifecycle

ancha run starts your agent for you. When your own harness starts the agent, such as a test suite, an eval loop or a notebook, use the world lifecycle commands instead. ancha world up starts a fresh world and prints its tools’ URLs and fake credentials. Your harness runs the agent with them. ancha check grades the world with the scene’s checks and the same exit codes as ancha run. ancha world down removes the world.

ancha world up --scene scenes/support-reply/scene.yaml --json   # envId, and env: the variables for your agent
# start your agent with exactly the variables in env
ancha check --env <envId> --json                                 # exit 1 when a required check fails
ancha world down --env <envId>

The agent gets the tools’ variables, the task and the world’s ID. It never gets the URL or token that controls the world.

ancha world up

ancha world up [options]

Option	Description
`--scene <file>`	Scene file to start (default: the one scene ancha.yaml names)
`--test <file>`	Test file to start; same as —scene
`--world <id>`	A saved world from ancha world list
`--on <where>`	local (this computer) or cloud (your workspace); default: where ancha run would run
`--seed <seed>`	Seed for ids and data (default: “<scene id>:1”)
`--ttl <duration>`	Remove the world after this long with no call from the agent and no ancha world or ancha check command on it (default: “30m”)

Pass at most one of --scene, --test and --world. With none, world up starts the scene that ancha.yaml names, when it names exactly one.

ancha world up --scene scenes/starter/scene.yaml

Output

running locally (worlds in a server on this computer, until ancha world down or 10 minutes without worlds)
world b1p97rm9 is ready (scene starter); it expires at 2026-10-31T10:55:25.457Z unless used
Give your agent these variables:
  SLACK_API_URL=http://127.0.0.1:56600/e/b1p97rm9/slack/api/
  SLACK_BOT_TOKEN=<fake token>
  SLACK_SIGNING_SECRET=<fake secret>
  SLACK_APP_TOKEN=<fake token>
  GITHUB_API_URL=http://127.0.0.1:56600/e/b1p97rm9/github
  GITHUB_TOKEN=<fake token>
  GITHUB_WEBHOOK_SECRET=<fake secret>
  ANCHA_ENV_ID=b1p97rm9
  ANCHA_SCENE_ID=starter
  ANCHA_TASK="Discover resources through the declared native service APIs. ..."
next: ancha check --env b1p97rm9 --json
next: ancha world down --env b1p97rm9

With --json, the result is one object:

Field	Meaning
`envId`	The world’s ID. Pass it to `check`, `state`, `trace` and `down`.
`workspace`	Where the world runs: `local:<project path>`, or the URL of the hosted world server.
`sceneId`	The scene’s `id`. Absent for a saved world.
`services`	Each tool’s URL and fake credentials, as objects.
`env`	The variables to give the agent: the tools’ variables, `ANCHA_ENV_ID`, and for a scene `ANCHA_SCENE_ID` and `ANCHA_TASK`.
`expiresAt`	When the world is removed unless something uses it.
`next`	The commands to run next.

Give the agent exactly the variables in env. See Environment variables. ancha schema world_up prints the JSON Schema of this output.

Where the world runs

world up chooses a server the way ancha run does: --server-url, then server.url in ancha.yaml, then ANCHA_SERVER_URL, then the workspace saved by ancha login. With none of these it starts a server on this computer, which stays up until ancha world down removes the last world or ten minutes pass without one. The first line says which:

running on hosted https://app.ancha.io/t/<workspace> (from ancha login; --local to run here)

--on local keeps the world on this computer whatever is configured. --on cloud puts it in your hosted workspace and exits 2 when no workspace is configured. A world in your workspace serves its tools at https://app.ancha.io/t/<workspace>/e/<envId>/<tool>. Your agent runs wherever your harness runs it. See Hosted workspace.

The lease

A world lives for --ttl after the last call from the agent or the last ancha world or ancha check command on it. The default is 30 minutes; the range is 1 second to 24 hours. Each of those renews the lease. After it expires, the world is gone and its commands fail with ENV_NOT_FOUND.

Saved worlds

--world <id> starts a world saved with ancha world create: its tools and starter data, with no task and no checks. ancha check then needs --test <file> to know which checks to apply.

ancha check

ancha check [options]

Option	Description
`--env <id>`	World id from ancha world up
`--test <file>`	Test or scene file whose checks to apply (default: the scene the world started from)
`--scene <file>`	Same as —test
`--check <json>`	A check to apply instead, as one JSON object (repeatable); each is required

check evaluates the checks against the world as it is now: the final state of the tools and every call the agent made. It does not end the world, so you can run it before and after the agent, or after each step.

ancha check --env b1p97rm9

Output

pass  slack_access
pass  github_access
verdict: pass (2 of 2 required checks pass)
next: ancha world down --env b1p97rm9

A failed check shows what was expected and what the world held:

Output

fail  slack_access: expected agent calls * /api/*.*; got never called; agent made 0 call(s)
fail  github_access: expected agent calls * /*repos*; got never called; agent made 0 call(s)
verdict: fail (0 of 2 required checks pass)
next: ancha world trace --env b1p97rm9 --json
next: ancha world down --env b1p97rm9

The file’s pass list decides which checks are required. A check outside it is evaluated, printed with (not required), and does not change the verdict. Judge checks need OPENROUTER_API_KEY in the shell that runs ancha check and use judge.model from ancha.yaml. See Checks. With --json:

Field	Meaning
`envId`, `workspace`, `sceneId`	The world, where it runs, and the scene whose checks applied.
`verdict`	`pass` or `fail`.
`checks`	Every result: `id`, `required`, `passed`, `status`, `expected`, `actual`, `explanation` and `evidence`. See Checks reference.
`failures`	The required checks that failed: `check`, `expected`, `actual`, `explanation`.
`next`	The commands to run next.

ancha schema check prints the schema.

ancha world state

ancha world state --env <id>

Prints the world’s current state, tool by tool, as JSON: Slack’s users, channels and messages, GitHub’s repositories, issues and pull requests, and so on for every tool in the world. The text output is the same JSON.

ancha world trace

ancha world trace [options]

Option	Description
`--env <id>`	World id from ancha world up
`--after <seq>`	Only entries after this sequence number (default: “0”)

Output

1  2026-10-21T14:00:00.858Z  agent  slack  GET /api/conversations.list  200
2  2026-10-21T14:00:00.864Z  agent  github  GET /repos/acme/starter  200

Each line is the sequence number, the simulated time, who made the call (agent, or the world itself), the tool, the method and path, and the status. Before any call it prints no calls yet. With --json, each entry also carries the response body and gap, which is true for a call to an endpoint the replica does not implement. Poll with --after <seq> to read only new entries.

ancha world down

ancha world down --env <id>

Output

world b1p97rm9 removed

Removing a world that is already gone prints world b1p97rm9 was already gone and exits 0. With --json, removed is false.

Exit codes and errors

Code	When
`0`	`world up`, `state`, `trace` and `down` succeeded, or `check` passed.
`1`	`check`: a required check failed.
`2`	Usage: two of `--scene`, `--test` and `--world`; `--on` with a value other than `local` or `cloud`; `--on cloud` without a workspace; a `--ttl` outside 1s to 24h; `check` on a world that has no checks to apply; `check` with both `--test` and `--scene`.
`3`	`ENV_NOT_FOUND`: the world expired, was removed, or its local server stopped. Start a new one with `ancha world up --json`.

Live worlds belong to the project directory you ran world up from, so run the other commands from the same directory. ancha world list lists saved worlds, not live ones.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

World lifecycle

ancha world up

Where the world runs

The lease

Saved worlds

ancha check

ancha world state

ancha world trace

ancha world down

Exit codes and errors

​ancha world up

​Where the world runs

​The lease

​Saved worlds

​ancha check

​ancha world state

​ancha world trace

​ancha world down

​Exit codes and errors

ancha world up

Where the world runs

The lease

Saved worlds

ancha check

ancha world state

ancha world trace

ancha world down

Exit codes and errors