self-hosted-sandboxes-reference changedmanaged-agents/self-hosted-sandboxes-reference
Nearest release: v2.1.288, published 3 hours after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+214added
Lines−0removed
From line
—
no hunk to open at
First seen
2 Oct 2026
this site's first read of the page
Recorded edits1to this page, all time
## CLI commands and flags ## Environment variables ## Host requirements ## Sandbox filesystem ## SDK helpers ### EnvironmentWorker ### Work poller ### Session tool runner ### AgentToolContext and the agent toolset
The whole hunk
214 lines, new page
/
lines
A whole new page. There's nothing to diff it against, so here is what it says.
---
title: Self-hosted worker reference
url: https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference
description: "Reference for self-hosted sandbox workers: ant CLI flags, environment variables, host requirements, filesystem paths, and SDK helper options."
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
This page documents the pre-built workers that serve a `self_hosted` environment. For task-oriented guides, start with [Self-hosted sandboxes](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes) and [Deploy self-hosted workers](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers).
## CLI commands and flags
| Command | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ant beta:worker poll` | Claims work items from the environment's queue and runs each session in process. With `--on-work`, calls your script for each work item instead. |
| `ant beta:worker run` | Handles one claimed session and exits. Use it as the entrypoint of a per-session sandbox. |
| Flag | Description |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--environment-id` | The environment to poll for work. Also reads from `ANTHROPIC_ENVIRONMENT_ID`. |
| `--environment-key` | Authenticates the worker with this environment. Also reads from `ANTHROPIC_ENVIRONMENT_KEY`. |
| `--workdir` | Directory where skills are downloaded and tools read and write files. Defaults to `.` (the current directory). |
| `--on-work` | Script to call for each claimed work item instead of running tools in-process. Receives session details as environment variables and the work item as JSON on standard input. |
| `--max-idle` | How long to wait after the session goes idle with an `end_turn` [stop reason](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons) before shutting down. Defaults to `60s`. |
| `--log-format` | Log output format. Use `json` for structured log ingestion. Defaults to `text`. |
## Environment variables
| Variable | Description | Set by |
| ------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ANTHROPIC_ENVIRONMENT_ID` | The environment whose queue the worker serves. | You, on the worker host. The poller passes it to the `--on-work` script. |
| `ANTHROPIC_ENVIRONMENT_KEY` | Authenticates the worker to its queue. | You, on the worker host. The poller passes it to the `--on-work` script. |
| `ANTHROPIC_SESSION_ID` | The session that a claimed work item represents. | The poller, for the `--on-work` script. |
| `ANTHROPIC_WORK_ID` | The claimed work item. | The poller, for the `--on-work` script. |
| `ANTHROPIC_WORK_SECRET` | The work item's per-session secret. | You. The poller does not set it. See [Forward the work item's secret](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret). |
| `ANTHROPIC_BASE_URL` | Overrides the default API endpoint. Optional. | You, on the worker host. |
| `ANTHROPIC_WEBHOOK_SIGNING_KEY` | Verifies incoming webhook payloads. | You, on a webhook handler host. |
## Host requirements
| Worker | Requirement |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| All workers | A Linux host with `/bin/bash` at that exact path. The worker's bash tool invokes it directly, without consulting `PATH`. |
| TypeScript SDK | `unzip` and `tar` on the `PATH`, and Node.js 22 or later. |
| Python and Go SDKs | No additional binaries. These SDKs use their standard libraries for archive extraction. |
[Memory stores](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#requirements) add their own requirements.
## Sandbox filesystem
| Path | Contents |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/workspace` | The system default working directory for tool execution and skill download. If you use a different working directory, update your agent's system prompt so Claude can locate the skill files. |
| `<workdir>/skills/<name>/` | The agent's downloaded skills. |
| `/mnt/memory/<store>/` | One directory per attached memory store, at the store's `mount_path` (for example, `/mnt/memory/user-preferences/`). The worker creates these directories when it claims the session and removes them when the session ends. |
On self-hosted environments the session's system prompt omits the `/mnt/session/outputs` instruction used on Anthropic-managed sandboxes. Final deliverables land wherever the agent writes them in your sandbox filesystem, typically under the working directory.
Skills can include executables that the agent may run directly. The CLI and SDK workers preserve the executable permissions recorded in the skill bundle when they extract it. If you implement skills download manually, you are responsible for setting executable permissions.
## SDK helpers
The Python, TypeScript, and Go SDKs provide three helpers at different levels of control:
| Helper | What it does | Use it when |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| [`EnvironmentWorker`](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference#environment-worker) | Handles polling, setup, and execution end to end. | Most cases. |
| [`work.poller()` (go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference#work-poller) | Polls the work queue and gives you each claimed session. | You determine what happens for each session, for example launching a sandbox rather than running tools in-process. |
| [`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference#session-tool-runner) | Runs tool calls for a single session, given the session ID and a tool list. | You've already claimed the work and only need the execution layer. |
### EnvironmentWorker
| Method | Description |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `run()` (go: `Run()`) | Runs indefinitely, picking up sessions as they arrive. |
| `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | Handles a single claimed work item and returns. Pass the work, session, and environment identifiers and the `work_secret` (typescript: `workSecret`; go: `WorkSecret`) explicitly, or let it read the [`ANTHROPIC_*` variables](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference#environment-variables). |
| Option | Description |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tools` (go: `ToolsFunc`) | A factory that receives the session's `AgentToolContext` and returns the tool list. Defaults to the standard agent toolset. |
| `memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) | How often attached memory stores reconcile with the server while the session runs. See [Sync interval](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#sync-interval). |
| `memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) | Whether files the agent deletes locally are also deleted from the store. See [Deletions](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#deletions). |
`EnvironmentWorker` manages the `AgentToolContext` and the toolset automatically. Pass a `tools` (go: `ToolsFunc`) factory to customize the tool list:
<CodeGroup exclude="shell">
```python Python
EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])
```
```typescript TypeScript
new EnvironmentWorker({
client,
environmentId,
environmentKey,
tools: (ctx) => [betaBashTool(ctx), myCustomTool]
});
```
```csharp C#
// EnvironmentWorker is not currently available in the C# SDK.
// To answer custom tool calls directly, see the session event stream.
```
```go Go
worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
EnvironmentID: environmentID,
EnvironmentKey: environmentKey,
ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool {
return []anthropic.BetaTool{agenttoolset.BetaBashTool(env), myCustomTool}
},
})
```
```java Java
// EnvironmentWorker is not currently available in the Java SDK.
// To answer custom tool calls directly, see the session event stream.
```
```php PHP
// EnvironmentWorker is not currently available in the PHP SDK.
// To answer custom tool calls directly, see the session event stream.
```
```ruby Ruby
# EnvironmentWorker is not currently available in the Ruby SDK.
# To answer custom tool calls directly, see the session event stream.
```
</CodeGroup>
### Work poller
| Option | Description |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `drain` (go: `Drain`) | Whether to stop polling once the queue is empty rather than waiting for new work. |
| `block_ms` (python; typescript: `blockMs`; go: `BlockMs`) | How long each poll waits for work to arrive before returning, in milliseconds. Must be between 1 and 999; the helper re-polls automatically. Pass `null` (typescript; python: `None`; go: `param.Null[int64]()`) for a non-blocking check. Defaults to a 999 ms long-poll. |
| `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | Re-claims work items that were claimed but never acknowledged within this many milliseconds. |
| `auto_stop` (typescript: `autoStop`; go: `AutoStop`) | Whether to post a stop signal for each work item once your loop body finishes with it. Set it to `false` (python: `False`; go: `param.NewOpt(false)`) when whatever runs the work item posts the stop itself. `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) does, and so does a sandbox you launch that owns the stop call. |
For a complete example, see [Launch sandboxes from the SDK poller](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers#launch-sandboxes-from-the-sdk-poller).
### Session tool runner
`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`) takes a tool list as `tools` (go: `Tools`). To build that list, set up `AgentToolContext` yourself and call `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`):
<CodeGroup exclude="shell">
```python Python
from anthropic.lib.tools.agent_toolset import (
AgentToolContext,
beta_agent_toolset_20260401,
)
async with AgentToolContext(
workdir="/workspace", client=client, session_id=work.data.id
) as env:
# skills downloaded to /workspace/skills/<name>/
tools = beta_agent_toolset_20260401(env)
```
```typescript TypeScript
import {
setupSkills,
betaAgentToolset20260401
} from "@anthropic-ai/sdk/tools/agent-toolset/node";
const ctx = { workdir: "/workspace", client, sessionId: work.data.id };
await setupSkills(ctx);
const tools = betaAgentToolset20260401(ctx);
```
```csharp C#
// AgentToolContext is not currently available in the C# SDK.
```
```go Go
env := &agenttoolset.AgentToolContext{Workdir: "/workspace"}
if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil {
panic(err)
}
// skills downloaded to /workspace/skills/<name>/
tools := agenttoolset.BetaAgentToolset20260401(env)
```
```java Java
// AgentToolContext is not currently available in the Java SDK.
```
```php PHP
// AgentToolContext is not currently available in the PHP SDK.
```
```ruby Ruby
# AgentToolContext is not currently available in the Ruby SDK.
```
</CodeGroup>
### AgentToolContext and the agent toolset
`AgentToolContext` is the execution context for tool calls. It defines the working directory and path policy, and can download the session's skills.
| Option | Description |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`) | Directories, in addition to the working directory, that the file tools (`read`, `write`, `edit`, `glob`, `grep`) can reach. |
| `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`) | Directories under which `write` and `edit` refuse paths. |
`EnvironmentWorker` adds the session's memory store directories to `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`) itself, and the directories of stores attached with `access: "read_only"` to `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`).
The confinement is a guardrail for the file tools only, not a sandbox. It does not constrain `bash`.
`beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`) takes an `AgentToolContext` and returns the standard tool implementations (`bash`, `read`, `write`, `edit`, `glob`, `grep`).
No line in this hunk matches that.