Self-hosted sandboxes

By default, Managed Agents executes tools and code inside Anthropic-managed cloud containers. Self-hosted sandboxes keep the orchestration on Anthropic's side but move tool execution into infrastructure you control, so the agent's code, filesystem, and network egress never leave your environment.

Self-hosted sandboxes are not yet available on Claude Platform on AWS.

How it differs from cloud environments

Self-hosting is a good fit when the agent needs to operate on data that cannot leave your network boundary, reach internal services that are not publicly routable, or run under your organization's own compliance and audit controls.

When to combine with MCP tunnels

Self-hosting controls where the agent's code executes. MCP tunnels controls how Anthropic reaches MCP servers in your network. They are independent: a session running in Anthropic's cloud containers can still reach private MCP servers through a tunnel, and a self-hosted session can use either tunneled or public MCP servers. Use both when you want execution and tool access to stay inside your boundary.

Environment worker

An environment worker is a process you run on your own infrastructure that receives tool execution requests from Anthropic and runs them locally. The self_hosted environment is a work queue connecting Anthropic's orchestration to your worker: when a session is assigned to an environment, Anthropic enqueues it as a work item. Your worker claims items from that queue, spawns an execution context for each session, downloads the agent's skills, runs tool calls locally, and posts results back.

Work is claimed by polling the environment's queue: either by an always-on worker that polls continuously, or a webhook-triggered handler that wakes on session.status_run_started and starts polling.

Both CLI and SDK include pre-built workers to orchestrate your sessions. The ant CLI supports the always-on pattern only; the SDK supports both always-on and webhook-triggered architectures.

The CLI and SDK both are configurable (see reference), but if you require more control, you can leverage the Environments Work endpoints directly and implement your own worker.

Sandbox filesystem

• /workspace: the default working directory for tool execution and skill download. Skills are downloaded to /workspace/skills/<name>/. If you change --workdir from the default, update your agent's system prompt so Claude knows where to find them.
• /mnt/session/outputs: the agent writes final output files to this path. When running in a container, mount a host directory here to retrieve them.

Start a session

Once your worker is running, create a session that targets the environment. Anthropic enqueues it and your worker claims and executes it.

File and GitHub resource mounting are handled in your container image rather than by Anthropic. To load your sandbox with session-specific files, you can pass session metadata when creating the session. Your orchestration layer can read that metadata and mount the relevant files before the worker starts executing.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

Reference

Monitoring and operations

These calls run from your monitoring or operations tooling, authenticated with your Claude API key, to observe and manage the worker fleet. The claim and keep-alive loop is handled inside the worker helpers, so you don't call those endpoints directly.

Read queue depth

work.stats returns the queue state for an environment:

• depth is the number of items waiting to be claimed. Scale your worker fleet or alert on backlog based on this value.
• pending is the number of items a worker has claimed and is currently processing.
• oldest_queued_at is the timestamp of the oldest item in the queue, or null if the queue is empty.
• workers_polling is the number of workers that have polled in the last 30 seconds. Use this for liveness alerting.

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

Stop a session gracefully

Use work.stop to ask the worker handling a specific session to shut it down cleanly. The worker finishes any in-flight tool call, posts a final status, and releases the session. Pass force: true in the request body to interrupt immediately instead of waiting for the current tool call to complete.

Because these calls run from your operations tooling rather than the worker host, ANTHROPIC_WORK_ID isn't set automatically. Set it to the target work item's ID before running the examples below.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)

Next steps