Environment variables

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

Event feed

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

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.
`ANCHA_SERVER_URL`	The Ancha server to use, after `--server-url` and `server.url`. See CLI overview.
`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.

Get started

Guides

Concepts

Tools

CLI

Reference

Cloud

Help

Environment variables

Tool variables

In `ancha run` and `ancha doctor`

Event feed

In playground and hosted runs

Variables the CLI reads

​Tool variables

​In ancha run and ancha doctor

​Event feed

​In playground and hosted runs

​Variables the CLI reads

Tool variables

In `ancha run` and `ancha doctor`

Event feed

In playground and hosted runs

Variables the CLI reads