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

> Create, list, reset and destroy environments from scene files on a running Ancha server, to point an agent or a script at a scene's tools by hand.

An environment is a live copy of a scene's world on a server. `ancha run` creates one per trial for you. Use `ancha env` to create one by hand, for example to develop against a scene's data while you write the agent.

Start a server first with [`ancha serve`](https://docs.ancha.io/cli/serve), or configure one.

## ancha env up

```bash theme={null}
ancha env up [options] <scene>
```

| Argument | Description |
| - | - |
| `scene` | Scene YAML file |

| Option | Description |
| - | - |
| `--seed <seed>` | Seed for ids and randomness (default: "\<scene id>:1") |
| `--ttl <duration>` | Wall-time lease from 1s to 24h (default: 30m) |

```bash theme={null}
ancha env up scenes/starter/scene.yaml
```

```text Output theme={null}
env opz1zm6z (scene starter)
  slack: http://127.0.0.1:4400/e/opz1zm6z/slack/api/  token <fake token>
  github: http://127.0.0.1:4400/e/opz1zm6z/github  token <fake token>
  datadog: http://127.0.0.1:4400/e/opz1zm6z/datadog  token <fake token>
  pagerduty: http://127.0.0.1:4400/e/opz1zm6z/pagerduty  token <fake token>
```

The environment expires after its lease, 30 minutes by default. `--json` returns the IDs, URLs and credentials for scripts.

## ancha env list

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

```text Output theme={null}
env opz1zm6z (scene starter)  created 2026-10-31T07:50:45.244Z  expires 2026-10-31T08:20:45.244Z
```

Sandboxes appear here too, with a `sandbox-…` scene ID.

## ancha env reset

```bash theme={null}
ancha env reset [options] <id>
```

| Argument | Description |
| - | - |
| `id` | Environment id |

```text Output theme={null}
reset env opz1zm6z in 2.6987499999813735 ms
```

Restores the environment's initial data. It keeps the same URLs and credentials.

## ancha env down

```bash theme={null}
ancha env down [options] <id>
```

| Argument | Description |
| - | - |
| `id` | Environment id |

```text Output theme={null}
env opz1zm6z destroyed
```

## Exit codes

`0` on success. `2` for an invalid scene. `3` when the server cannot be reached or the environment does not exist (`ENV_NOT_FOUND`).


## Related topics

- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)
- [ancha.yaml](https://docs.ancha.io/reference/ancha-yaml.md)
- [World lifecycle](https://docs.ancha.io/cli/world-lifecycle.md)
- [ancha serve](https://docs.ancha.io/cli/serve.md)
- [CLI overview](https://docs.ancha.io/cli/overview.md)


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