Claude Platform Docs
Managed AgentsSelf-hosted sandboxes

Run one sandbox per session

Give each session its own self-hosted sandbox with the Helm chart on Kubernetes, a spawn script, or the SDK poller.

In the sandbox-per-session pattern, each session runs in a fresh sandbox, which can have its own filesystem, resource limits, and network controls. To compare it with the other patterns, see Choose a deployment pattern.

You can set it up in three ways:

  • Helm chart on Kubernetes: Anthropic’s dispatcher claims work and starts a pod for each session on your cluster.
  • Spawn script: The ant CLI claims work and calls your script, which launches a sandbox on any platform.
  • SDK poller: Your own code claims work and launches the sandbox.

The sections after Run sandboxes on Kubernetes apply to the spawn script and the SDK poller.

Run sandboxes on Kubernetes

Anthropic publishes a Helm chart, cma-sandboxes, and its images. The chart runs one sandbox per session on your own Kubernetes cluster. Its dispatcher polls the environment’s work queue and gives each session a pod of its own:

  • Isolation: Each pod runs under gVisor behind the chart’s network policies. It has its own filesystem and resource limits. Only the dispatcher holds the environment key.
  • Session affinity: Every message in a session goes to that session’s sandbox. After the session is idle for 30 minutes (the default of the chart’s sandbox.idleTimeout setting), its pod stops. Its /workspace volume stays until the session ends. The next message starts a pod on the same volume.
  • Warm pool: Except on Google Kubernetes Engine (GKE), the chart keeps two pods ready for new sessions (the default of the chart’s sandbox.warmPoolSize setting).

Sandbox pods run the ant CLI worker. They support memory stores with the default sync settings, and they don’t support custom tools.

Install the chart

The chart runs on GKE, Amazon EKS, and other clusters. Set up the following before you install it:

  • In the cluster: The Agent Sandbox controller (on GKE, the Agent Sandbox add-on), nodes that run gVisor, and a network plugin that enforces NetworkPolicy.
  • In your own namespace: Restricted Pod Security Standard labels, a Secret with the environment ID and environment key, and the dispatcher’s TLS certificate.

The install guide on GitHub has the setup steps for each kind of cluster. It also covers upgrades and key rotation.

Save your settings as cma-values.yaml. The install fails without the three settings in this file:

cma-values.yaml
platform: gke             # or eks, or generic for any other cluster
egress:
  # The chart already blocks the private ranges. List your other addresses
  # that sandboxes must not reach.
  clusterCIDRs:
    - 203.0.113.10/32     # your cluster's Kubernetes API endpoint
  cmaServer:
    public: true          # the Claude API has a public address

The install guide lists the settings that depend on your cluster, such as gke.dns on GKE Autopilot. It also says when egress.clusterIsPrivate: true takes the place of egress.clusterCIDRs.

Then, install the chart:

helm install cma \
  oci://us-docker.pkg.dev/anthropic-public-registry/sandboxes/charts/cma-sandboxes \
  --version 0.1.0 \
  --namespace cma \
  -f cma-values.yaml \
  --wait

After the install, run the preflight check that the install guide describes.

Add tools to the sandbox image

The published sandbox image is Alpine Linux with bash, curl, jq, and the ant CLI. The chart runs it with a read-only root filesystem and as a non-root user, so an agent can’t install packages during a session.

To give your agents more tools, such as Python or Git, build both images from the repository at the release’s tag. The Install section of the install guide has the commands. Push the images to your registry as cma-dispatcher and cma-sandbox, with the chart’s version as the tag. Then, set image.registry to that registry. If you pin image digests, use the digests of your own images.

Restrict network egress

By default, the chart’s network policies let a sandbox reach the public IPv4 internet. They block private address ranges, the cloud metadata server, and the addresses in egress.clusterCIDRs. A prompt-injected agent can send what it reads to any address that its sandbox can reach. Network egress in the install guide has the details.

  • GKE with Dataplane V2: Set egress.mode: fqdnGke to limit connections to port 443 on the hosts in egress.fqdnGke.hosts. Keep api.anthropic.com in that list, and add every host that your agents’ commands need. Unlike the default, this mode has no list of blocked ranges. It allows whatever address a listed host’s name resolves to, so list only hosts whose DNS you trust. A sandbox can still send data out inside DNS lookups.
  • Other clusters and GKE without Dataplane V2: The default is the only mode.
  • Every cluster: Network policies don’t cover the ports that the cluster’s own nodes listen on. See Node isolation you own in the install guide.

Launch sandboxes with a spawn script

A poller on the host claims work and calls your script once for each work item. The script launches a sandbox for that one session.

  1. Build the sandbox image

    Install ant and set ant beta:worker run as the entrypoint. When a sandbox starts, it reads session details from environment variables, handles that session, and exits. The base image must provide /bin/bash; the build uses curl only to download ant.

    Dockerfile
    FROM your-base-image
    ARG ANT_VERSION=2.11.0
    ARG TARGETARCH
    RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \
        curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \
          | tar -xz -C /usr/local/bin ant
    WORKDIR /workspace
    VOLUME /workspace
    ENTRYPOINT ["ant", "beta:worker", "run"]
  2. Write the spawn script

    The script forwards the session details into a fresh sandbox. It requires jq on the poller host.

    spawn.sh
    #!/bin/bash
    # spawn.sh: called once for each claimed work item
    # The claimed work item arrives as JSON on stdin.
    ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')"
    export ANTHROPIC_WORK_SECRET
    mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID"
    exec docker run --rm \
      -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \
      -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \
      -e ANTHROPIC_WORK_SECRET \
      -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \
      your-image

    The poller sets ANTHROPIC_WORK_ID, ANTHROPIC_ENVIRONMENT_ID, ANTHROPIC_SESSION_ID, and ANTHROPIC_ENVIRONMENT_KEY. ANTHROPIC_BASE_URL reaches the script only if you set it on the poller’s host. The script reads ANTHROPIC_WORK_SECRET from the work item’s JSON on standard input. See Environment variables.

    /host/outputs is a host directory you choose. Mounting it at /workspace lets you retrieve the session’s deliverables after the sandbox exits. The mount also picks up the downloaded skills/ tree and any intermediate files.

  3. Start the poller

    ant beta:worker poll --on-work ./spawn.sh

Forward the work item’s secret

Each claimed work item can carry a secret that Anthropic issues for that session. The worker that runs the session needs it to mount memory stores.

A worker that claims and runs sessions in one process passes the secret along itself. EnvironmentWorker with run() is one such worker, and ant beta:worker poll without --on-work is another. When your own code sits between the claim and the worker, you forward the secret:

You claim work withThe secret arrives asPass it to the worker as
ant beta:worker poll --on-workThe secret field of the work item JSON on your script’s standard inputANTHROPIC_WORK_SECRET in the sandbox’s environment
The Python, TypeScript, or Go SDK’s work.poller()The secret field of each claimed work itemANTHROPIC_WORK_SECRET in the sandbox’s environment or the work_secret argument to handle_item()

Pass the secret only into the sandbox that serves that session, and never log it. See Security model for how it relates to the environment key.

Launch sandboxes from the SDK poller

To claim work from your own code instead of ant beta:worker poll --on-work, use the poller in the Python, TypeScript, or Go SDK: work.poller(). It polls the queue and gives you each claimed session, and you launch the sandbox:

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork

SANDBOX_ENV = (
    "ANTHROPIC_ENVIRONMENT_ID",
    "ANTHROPIC_ENVIRONMENT_KEY",
    "ANTHROPIC_WORK_ID",
    "ANTHROPIC_SESSION_ID",
    "ANTHROPIC_WORK_SECRET",
    "ANTHROPIC_BASE_URL",  # forwarded only when set on this host
)


async def launch_container(work: BetaSelfHostedWork) -> None:
    print(f"claimed session {work.data.id}")
    # Replace `docker run` with your own sandbox launcher. Forward the environment
    # key (never your API key) and the work item's per-session secret: the worker
    # inside needs the secret to mount the session's memory stores.
    env = os.environ | {
        "ANTHROPIC_WORK_ID": work.id,
        "ANTHROPIC_SESSION_ID": work.data.id,
        "ANTHROPIC_WORK_SECRET": work.secret or "",
    }
    forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)]
    launcher = await asyncio.create_subprocess_exec(
        "docker", "run", "--rm", "--detach", *forward, "your-image", env=env
    )
    await launcher.wait()


async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key) as client:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

Run the SDK worker inside the sandbox

Replace the ant beta:worker run entrypoint with an SDK entrypoint when the sandbox must serve custom tools or use non-default memory sync settings. The entrypoint constructs EnvironmentWorker and calls handle_item(), which reads the same ANTHROPIC_* variables that the spawn script forwards.

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic
from anthropic.lib.environments import EnvironmentWorker


async def main() -> None:
    async with AsyncAnthropic(
        auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    ) as client:
        worker = EnvironmentWorker(client, workdir="/workspace")
        # With no arguments, handle_item() reads the ANTHROPIC_* variables the spawn
        # script forwarded, including ANTHROPIC_WORK_SECRET.
        task = asyncio.create_task(worker.handle_item())
        # Canceling the task when the container is stopped lets the worker upload
        # changed memory files and remove the store directories before it exits.
        loop = asyncio.get_running_loop()
        for signum in (signal.SIGINT, signal.SIGTERM):
            loop.add_signal_handler(signum, task.cancel)
        with contextlib.suppress(asyncio.CancelledError):
            await task


asyncio.run(main())

Stage files for a session

Anthropic doesn’t mount files or GitHub repositories into self-hosted sandboxes. To make session-specific files available:

  1. Pass file references, such as an S3 path or commit SHA, in the session’s metadata field.
  2. In your spawn script or --on-work handler, retrieve the session (GET /v1/sessions/{session_id}) and read metadata. The claimed work item carries the session ID but not the metadata.
  3. Stage the files into the working directory before any tool runs.

The cURL sample reads an access token from ANTHROPIC_AUTH_TOKEN. To get one, set up Workload Identity Federation with the default workspace:developer scope, as Set up federation describes. Then, exchange your workload’s identity token for an access token, as Authenticate from your workload shows. Set ANTHROPIC_AUTH_TOKEN only in the shell where you run the cURL sample, because it takes precedence over your federation settings. Authentication lists the other credentials that the API accepts, such as the API key from the quickstart.

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

Next steps

Read queue depth, stop sessions and workers cleanly, and fix common failures.

Was this page helpful?