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

# Environment variables

> Every variable Ancha sets for your agent (tool URLs and fake credentials, task, trial and attempt variables, event feed endpoints), what the agent inherits from your shell, and every variable the ancha CLI reads.

Ancha passes everything your agent needs through environment variables. Only the tools in the world get variables. All credentials are fake and work only against that trial's or attempt's tools.

## Tool variables

| Tool | Variables |
| - | - |
| Slack | `SLACK_API_URL` (ends in `/api/`), `SLACK_BOT_TOKEN`, `SLACK_SIGNING_SECRET`, `SLACK_APP_TOKEN` |
| GitHub | `GITHUB_API_URL`, `GITHUB_TOKEN`, `GITHUB_WEBHOOK_SECRET` |
| Datadog | `DATADOG_API_URL`, `DD_API_KEY`, `DD_APP_KEY`, `DATADOG_WEBHOOK_TOKEN` |
| PagerDuty | `PAGERDUTY_API_URL`, `PAGERDUTY_API_TOKEN`, `PAGERDUTY_FROM_EMAIL`, `PAGERDUTY_ROUTING_KEY`, `PAGERDUTY_ROUTING_KEYS` (JSON, by service ref), `PAGERDUTY_SIGNING_SECRET` |
| HubSpot | `HUBSPOT_API_URL`, `HUBSPOT_ACCESS_TOKEN` |
| Salesforce | `SALESFORCE_INSTANCE_URL`, `SALESFORCE_ACCESS_TOKEN` |
| Gong | `GONG_API_URL`, `GONG_ACCESS_KEY`, `GONG_ACCESS_KEY_SECRET` |
| Google Analytics | `GA4_API_URL`, `GA4_ACCESS_TOKEN` |
| Google Ads | `GOOGLE_ADS_API_URL`, `GOOGLE_ADS_ACCESS_TOKEN`, `GOOGLE_ADS_GRPC_ENDPOINT`, `GOOGLE_ADS_TLS_ROOT_CERT_BASE64` |
| LinkedIn Ads | `LINKEDIN_ADS_API_URL`, `LINKEDIN_ADS_TOKEN` |
| ChatGPT Ads | `OPENAI_ADS_API_URL`, `OPENAI_ADS_API_KEY` |
| Open-Meteo | `OPEN_METEO_API_URL`, `OPEN_METEO_GEOCODING_URL` |
| Gmail | `GMAIL_API_URL`, `GMAIL_ACCESS_TOKEN` |
| Google Drive | `GOOGLE_DRIVE_API_URL`, `GOOGLE_DRIVE_ACCESS_TOKEN` |
| Microsoft Word | `MICROSOFT_GRAPH_API_URL`, `MICROSOFT_GRAPH_ACCESS_TOKEN` |
| Notion | `NOTION_API_URL`, `NOTION_TOKEN` |
| Dropbox | `DROPBOX_API_URL`, `DROPBOX_ACCESS_TOKEN` |
| Resend | `RESEND_BASE_URL`, `RESEND_API_KEY` |
| Better Stack | `BETTER_STACK_API_URL`, `BETTER_STACK_API_TOKEN` |
| Linear | `LINEAR_API_URL`, `LINEAR_API_KEY` |
| Jira | `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` |
| Okta | `OKTA_ORG_URL`, `OKTA_API_TOKEN` |
| Amazon S3 | `AWS_ENDPOINT_URL_S3`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` |
| Clerk | `CLERK_API_URL`, `CLERK_SECRET_KEY` |
| Attio | `ATTIO_API_URL`, `ATTIO_API_KEY` |
| Stripe | `STRIPE_API_URL`, `STRIPE_SECRET_KEY`, `STRIPE_API_HOST_URL` |
| PayPal | `PAYPAL_API_URL`, `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET` |
| Shopify | `SHOPIFY_API_URL`, `SHOPIFY_ACCESS_TOKEN`, `SHOPIFY_API_VERSION` |
| Lob | `LOB_API_URL`, `LOB_API_KEY`, `LOB_ASSETS_URL` |
| Kalshi | `KALSHI_API_URL`, `KALSHI_API_KEY_ID`, `KALSHI_PRIVATE_KEY` |

Locally, URLs look like `http://127.0.0.1:<port>/e/<environment-id>/<tool>`; with a hosted workspace, `https://app.ancha.io/t/<workspace>/e/<environment-id>/<tool>`. An agent that reads these variables runs unchanged against the real services when you set them to real values. See [Tools](https://docs.ancha.io/tools/overview.md) for how each tool expects its credentials, and `ancha connect <tool>` for the exact names.

## In `ancha run` and `ancha doctor`

| Variable | Value |
| - | - |
| `ANCHA_TASK` | The scene's `task`. With `agent.input: per_event`, a one-line summary of the event: who said what, where. |
| `ANCHA_EVENT_JSON` | With `agent.input: per_event`, the event's native payload. |
| `ANCHA_SCENE_ID` | The scene's `id`. |
| `ANCHA_TRIAL` | The trial number, from 1. |
| `ANCHA_ENV_ID` | The ID of the trial's environment. |
| `ANCHA_ATTEMPT_ID`, `ANCHA_CASE_ID` | IDs of this attempt and its case. |
| `ANCHA_STATE_DIR` | An empty directory for the agent's files and memory, fresh per trial. |
| `ANCHA_EVENTS_URL`, `ANCHA_EVENTS_TOKEN` | The trial's event feed. See below. |
| `ANCHA_CONTEXT_URL` | Returns `{env, session, task}` for the trial. Same token. |
| `ANCHA_DONE_URL`, `ANCHA_TRIAL_TOKEN` | POST `{}` here with `Authorization: Bearer <ANCHA_TRIAL_TOKEN>` to end the trial early. |
| `ANCHA_AGENT_PORT` | The port to listen on, for endpoint agents. |

Besides these, the agent process gets `agent.env` from `ancha.yaml` and a base set from your shell: `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `LANG`, `LC_*`, `TERM`, `TMPDIR`, `TZ`, `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `VIRTUAL_ENV`, `CONDA_PREFIX` and `PYTHONPATH`. Any other variable, such as a provider key, reaches it only when you name it in `agent.pass_env` or with `--pass-env NAME`. `--inherit-env` passes the whole shell. When a run is uploaded to your workspace, the values of the variables passed this way are replaced with `[redacted]` first. With `agent.execution.mode: container`, the agent gets only Ancha's variables and the names listed in `agent.execution.env`. See [`ancha run`](https://docs.ancha.io/cli/run#what-the-agent-gets).

A world from `ancha world up` gives the agent the tool variables, `ANCHA_ENV_ID`, `ANCHA_SCENE_ID` and `ANCHA_TASK`, and nothing that controls the world. See [World lifecycle](https://docs.ancha.io/cli/world-lifecycle.md).

### Event feed

Agents that react to events, such as a Slack bot answering messages, read them from the feed:

```js theme={null}
const url = new URL(process.env.ANCHA_EVENTS_URL);
url.searchParams.set('after', String(cursor));   // start at 0
url.searchParams.set('wait_ms', '25000');         // long-poll, 0 to 25000
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.ANCHA_EVENTS_TOKEN}` } });
const { events, cursor: next } = await res.json();
```

Each event has `cursor`, `id`, `service`, `type`, `tSim`, `body` and `headers`. `body` is the exact JSON the real service would send, as a string, and `headers` holds its signature headers. Save `cursor` after each batch, even an empty one. The feed can be replayed: asking again with an old cursor returns the same events. Events for tools delivered over HTTP or Socket Mode do not appear in the feed.

## In playground and hosted runs

| Variable | Value |
| - | - |
| `ANCHA_TASK` | The task's prompt. |
| `ANCHA_ATTEMPT_ID` | The attempt's ID. |
| `ANCHA_ENV_ID` | The attempt's environment. |
| `ANCHA_STATE_DIR` | `/state`, fresh per attempt. |
| `ANCHA_AGENT_PORT` | The port an HTTP agent listens on. |
| `ANCHA_CONNECTION_MANIFEST` | Path to a JSON file that describes the attempt's tools and endpoints. |
| `SLACK_MCP_URL`, `ANCHA_MCP_URL` | A Slack MCP endpoint, when the world has Slack. |
| `OPENROUTER_BASE_URL`, `ANCHA_MODEL_URLS` | Local routes to the model providers the agent's profile allows. |

Plus the tool variables above. Provider keys you saved with `ancha secrets set` reach agents in the hosted workspace that declare that provider.

## Variables the CLI reads

| Variable | Used for |
| - | - |
| `ANCHA_JSON` | `1` makes every command behave as if `--json` were passed. |
| `ANCHA_UPLOAD` | `1` makes `ancha run` send each finished run to your workspace, like `--upload`. See [Results in your workspace](https://docs.ancha.io/cloud/results.md). |
| `ANCHA_SERVER_URL` | The Ancha server to use, after `--server-url` and `server.url`. See [CLI overview](https://docs.ancha.io/cli/overview.md#which-server-a-command-uses). |
| `ANCHA_API_KEY` | The API key for a hosted server. It wins over the key saved by `ancha login`. |
| `ANCHA_CREDENTIALS_FILE` | Where `ancha login` saves keys. Default `$XDG_CONFIG_HOME/ancha/credentials.json`, or `~/.config/ancha/credentials.json`. |
| `OPENROUTER_API_KEY` | Judge checks in `ancha run` and `ancha check`, and `ancha world gen`. Also an agent profile's key with `--credential-source env`. The agent itself gets it only through `agent.pass_env`. |
| `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` | Agent profiles with `--provider openai` or `anthropic` and `--credential-source env`. |
| `ANCHA_DOCKER_CONTEXT` | The Docker context for container runs. |
| `ANCHA_HARBOR_PYTHON` | The Python interpreter `ancha execution prepare` uses instead of `python3.12` or `python3.13`. |

`ancha secrets set NAME` reads `NAME` from your shell. See [`ancha secrets`](https://docs.ancha.io/cli/secrets).


## Related topics

- [Tools](https://docs.ancha.io/tools/overview.md)
- [For coding agents](https://docs.ancha.io/coding-agents.md)
- [Attempts and runs](https://docs.ancha.io/concepts/attempts-and-runs.md)
- [ancha.yaml](https://docs.ancha.io/reference/ancha-yaml.md)
- [ancha run](https://docs.ancha.io/cli/run.md)


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