1# Managed Agents — Self-Hosted Sandboxes
2 
3With `config.type: "self_hosted"`, the **agent loop stays on Anthropic's orchestration layer** but **tool execution moves to infrastructure you control** — bash, file ops, and code run inside your container, so filesystem contents and network egress never leave your environment. Contrast with `config.type: "cloud"`, where Anthropic runs the container. Connectivity is **outbound-only**: your worker long-polls Anthropic's work queue; Anthropic never dials into your network.
4 
5## Flow
6 
7```
81. Create environment:      config: {type: "self_hosted"}        → env_...
92. Generate environment key (Console, on the environment page)   → sk-ant-oat01-...  as ANTHROPIC_ENVIRONMENT_KEY
103. Run a worker:            EnvironmentWorker.run()  or  ant beta:worker poll
114. Sessions reference       environment_id=env_... exactly as for cloud
12```
13 
14## Create the environment
15 
16```python
17client = anthropic.Anthropic()
18 
19environment = client.beta.environments.create(
20    name="self-hosted", config={"type": "self_hosted"}
21)
22```
23 
24`{"type": "self_hosted"}` is the entire config — there are no pool, capacity, or networking sub-fields; you control those on your side.
25 
26## Run a worker — SDK (primary path)
27 
28`EnvironmentWorker` wraps the poll → dispatch → tool-execute loop. `.run()` is the always-on loop; `.run_one()` / `.runOne()` handles one work item (for webhook-driven wake).
29 
30**Python — always-on:**
31 
32```python
33import asyncio
34import os
35from anthropic import AsyncAnthropic
36from anthropic.lib.environments import EnvironmentWorker
37 
38 
39async def main() -> None:
40    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
41    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
42    async with AsyncAnthropic(auth_token=environment_key) as client:
43        await EnvironmentWorker(
44            client,
45            environment_id=environment_id,
46            environment_key=environment_key,
47            workdir="/workspace",
48        ).run()
49 
50 
51asyncio.run(main())
52```
53 
54**TypeScript — always-on:**
55 
56```typescript
57import Anthropic from "@anthropic-ai/sdk";
58import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";
59 
60const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
61const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
62const client = new Anthropic({ authToken: environmentKey });
63const ctrl = new AbortController();
64process.once("SIGTERM", () => ctrl.abort());
65 
66await new EnvironmentWorker({
67  client,
68  environmentId,
69  environmentKey,
70  workdir: "/workspace",
71  signal: ctrl.signal
72}).run();
73```
74 
75**Customizing tools.** `EnvironmentWorker` runs the built-in toolset by default. To add or replace tools, use `AgentToolContext(workdir=, client=, session_id=)` with `beta_agent_toolset(env)` / `betaAgentToolset(env)` and pass the resulting tools to the lower-level `tool_runner()`. Skills attached to the agent are downloaded into `{workdir}/skills/<name>/` before tool calls begin (`AgentToolContext` handles this when given `client` and `session_id`). Downloaded skill files are marked executable automatically by the CLI and SDK; if you implement skills download yourself, you set permissions.
76 
77> **Runtime deps:** the SDK helpers require `/bin/bash` at that exact path. The TypeScript SDK additionally requires `unzip`, `tar`, and Node.js 22+. These are resolved at fixed paths and do **not** respect `PATH` overrides.
78 
79## Run a worker — `ant` CLI (fixed tools)
80 
81The `ant` CLI ships a worker with the fixed built-in toolset (`bash`, `read`, `write`, `edit`, `glob`, `grep`). Install per `shared/anthropic-cli.md`, then:
82 
83```sh
84export ANTHROPIC_ENVIRONMENT_KEY=sk-ant-oat01-...
85ant beta:worker poll --environment-id env_... --workdir /workspace
86```
87 
88- `--workdir` is the directory tools operate in (default `.`); tool calls are sandboxed to it.
89- `--environment-key` overrides the env var.
90- `--on-work <script>` runs your script per work item (e.g. to spin a fresh container per session — see Container orchestration below).
91- `--unrestricted-paths`, `--max-idle` (default `60s`), `--log-format` — see `ant beta:worker poll --help`.
92- Flags fall back to env vars (`ANTHROPIC_ENVIRONMENT_ID`, `ANTHROPIC_ENVIRONMENT_KEY`).
93- Exits cleanly on SIGTERM/SIGINT after draining in-flight work.
94- **Fixed toolset** — for custom tools, use the SDK worker above.
95 
96Inside an `--on-work` container, run `ant beta:worker run --workdir <dir>` as the entrypoint.
97 
98## Webhook-driven wake (instead of always-on)
99 
100Register a webhook for `session.status_run_started` (see `shared/managed-agents-webhooks.md`), verify the delivery, then drain one work item with `.run_one()`:
101 
102```python
103import os
104import anthropic
105from anthropic.lib.environments import EnvironmentWorker
106 
107environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
108environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
109client = anthropic.AsyncAnthropic(
110    auth_token=environment_key,
111)  # reads ANTHROPIC_WEBHOOK_SIGNING_KEY from env for webhooks.unwrap()
112 
113 
114async def handle(raw: bytes, headers: dict[str, str]) -> dict:
115    event = client.beta.webhooks.unwrap(raw.decode(), headers=headers)
116    if event.data.type != "session.status_run_started":
117        return {"status": "ignored"}
118    await EnvironmentWorker(
119        client,
120        environment_id=environment_id,
121        environment_key=environment_key,
122        workdir="/workspace",
123    ).run_one()
124    return {"status": "ok"}
125```
126 
127TypeScript: same shape with `client.beta.webhooks.unwrap(body, {headers})` and `new EnvironmentWorker({...}).runOne()`.
128 
129## Container orchestration (mid-level)
130 
131`EnvironmentWorker.run()` polls and executes tools in the same process. To run each session in its **own** container, use the mid-level poller in a thin orchestrator — Python `client.beta.environments.work.poller(environment_id=, environment_key=, drain=, block_ms=, reclaim_older_than_ms=, auto_stop=)`; TypeScript `new WorkPoller({client, environmentId, environmentKey, autoStop})` from `@anthropic-ai/sdk/helpers/beta/environments` — and, for each yielded `work` item, start a fresh container with these env vars injected, whose entrypoint runs `ant beta:worker run` or an `EnvironmentWorker(...).run_one()`. `block_ms` is 1–999 (or `None` for non-blocking); `reclaim_older_than_ms` re-claims items leased to a dead worker; `drain` stops once the queue is empty; `auto_stop` posts a stop signal after the iterator exits (set `False` when the launched container owns the stop call). **Go's poller has no `auto_stop` opt-out** — it calls `work.Stop` when the handler returns, so block in the handler until the session completes rather than detaching.
132 
133| Env var | Value |
134|---|---|
135| `ANTHROPIC_SESSION_ID` | `work.data.id` |
136| `ANTHROPIC_WORK_ID` | `work.id` |
137| `ANTHROPIC_ENVIRONMENT_ID` | `work.environment_id` |
138| `ANTHROPIC_ENVIRONMENT_KEY` | pass through |
139| `ANTHROPIC_BASE_URL` | pass through |
140 
141Skip items where `work.data.type != "session"`.
142 
143## Monitoring & control
144 
145These are **control-plane** calls — authenticate with `x-api-key` (not the environment key); `managed-agents-2026-04-01` beta header. **Call them from outside the worker host** — setting `ANTHROPIC_API_KEY` on the worker host exposes an organization-scoped credential to agent tool calls.
146 
147| SDK (`client.beta.environments.work.*`) | REST | CLI | Returns |
148|---|---|---|---|
149| `stats(environment_id)` | `GET /v1/environments/{id}/work/stats` | `ant beta:environments:work stats` | `{type:"work_queue_stats", depth, pending, oldest_queued_at, workers_polling}` |
150| `stop(work_id, environment_id=)` | `POST /v1/environments/{id}/work/{work_id}/stop` | `ant beta:environments:work stop` | `work.state` |
151 
152## What changes vs `cloud`
153 
154| Concern | `cloud` | `self_hosted` |
155|---|---|---|
156| Container lifecycle, hardening, networking | Anthropic | **You** — run non-root, read-only rootfs, drop caps; egress is whatever your VPC/firewall allows |
157| `file` / `github_repository` resource mounting | Anthropic mounts into the container | **You** — pass pointers via `sessions.create(metadata={...})` and have your orchestrator fetch/clone before dispatch |
158| `memory_store` resources | Supported | **Not yet supported** |
159| Vault `environment_variable` credentials | Supported (substituted at Anthropic-managed egress) | **Not yet supported** — egress is yours, so there's nowhere to substitute the secret. Use MCP credentials or a host-side custom tool (`shared/managed-agents-client-patterns.md` Pattern 9) |
160| Built-in tools | Via `agent_toolset_20260401` | Supplied by your worker (`EnvironmentWorker` default / `beta_agent_toolset(env)` / `ant` CLI fixed set) |
161| Skills download | Automatic | `EnvironmentWorker` / `AgentToolContext` fetch into `{workdir}/skills/` (needs `client` + `session_id`) |
162| Claude Platform on AWS | Supported | **Not available** |
163| SDK worker helpers | All SDKs | **Python, TypeScript, Go only** (`EnvironmentWorker` / poller not in Java, Ruby, PHP, or C#) — use one of those three or the `ant` CLI |
164 
165## Credentials
166 
167| Credential | Format | Scope |
168|---|---|---|
169| `ANTHROPIC_ENVIRONMENT_KEY` | `sk-ant-oat01-...` | One environment's work queue. Generate in Console ("Generate environment key"). Pass as `auth_token=` / `authToken` on the client **and** as `environment_key=` / `environmentKey` on `EnvironmentWorker`. Store in a secrets manager; rotate on exposure. |
170| `ANTHROPIC_WEBHOOK_SIGNING_KEY` | `whsec_...` | Webhook signature verification (if using webhook-driven wake). The SDK reads this env var automatically for `client.beta.webhooks.unwrap()`. |
171 
172## Security — what you own
173 
174Container hardening; egress restriction (there is no default); `ANTHROPIC_ENVIRONMENT_KEY` custody and rotation; one workspace + environment per trust boundary when running untrusted code; least-privilege for the tool process; log retention and redaction. **Anthropic cannot**: fast-revoke a leaked environment key, verify your image or supply chain, sandbox tool execution inside your container, or enforce retention after tool output reaches your infrastructure. See the Self-Hosted Sandboxes Security page in `shared/live-sources.md` for the full checklist.
175