For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Host sandboxes for Claude Managed Agents
Run the code execution sandboxes of Claude Managed Agents on your own cluster, while Anthropic hosts the agent loop.
Warning
This integration is experimental. Its settings are environment variables with the EXPERIMENTAL_ prefix, and they can change in a future release without notice.
Claude Managed Agents can run their tools in a self-hosted sandbox. Anthropic hosts the agent loop, and your infrastructure runs the code that the agent executes. kagent can be that infrastructure. The kagent controller claims work from an Anthropic self-hosted environment, creates a Sandbox for each Claude Session, and starts Anthropic’s worker in it. The Sandbox suspends when the Session is idle, and it resumes with its files intact when the Session continues.
How it works
The integration is a launcher in the kagent controller. It is off by default, and it reads its settings from controller environment variables.
- The launcher polls your Anthropic environment for work. It authenticates with the environment key, which stays in the controller and never enters a Sandbox.
- When a Claude Session needs a sandbox, the launcher creates a kagent Sandbox from the SandboxTemplate that you configure, named
anthropic-<session-id>. - The launcher starts
ant beta:worker runin the Sandbox, with/data/workspaceas the working directory. The worker receives only the credentials that are scoped to that piece of work. - The worker runs the agent’s tool calls until the Session is idle for 5 minutes, and then exits. The launcher then suspends the Sandbox, which releases its compute.
- When the same Claude Session needs its sandbox again, the launcher resumes the Sandbox and starts a new worker. The files under
/dataare still there.
Each Sandbox lives for 12 hours by default, after which kagent deletes it, even if it is suspended. Only the leader controller replica runs the launcher.
| Where the agent loop runs | What runs in your cluster |
|---|---|
| On the Claude Platform, as a Claude Managed Agent | One Sandbox per Claude Session, running the ant worker and the agent’s tool calls |
Before you begin
Install the
antcommand line interface (CLI), and sign in.Create a self-hosted environment on the Claude Platform, and generate its environment key. Save both values.
export ANTHROPIC_ENVIRONMENT_ID=env_xxx export ANTHROPIC_ENVIRONMENT_KEY="<environment-key>"Install kagent from a build that includes the integration, and set the sandbox values.
Set up the Sandbox template
The launcher runs the ant CLI inside the Sandbox, so the template’s tools image must include it. The experimental image pinned in the blog includes the ant CLI. It is separate from the installation’s config.sandboxes.guestImage, which supplies kagent’s process and file service. This draft uses the blog’s tools image while the integration is under development.
Create an EgressPolicy that lets the worker reach Anthropic, and a SandboxTemplate that selects it. Every Sandbox has no outbound access by default, and the worker cannot run without access to the Anthropic API.
kubectl apply -f - <<'EOF' apiVersion: api.kagent.dev/v1alpha3 kind: EgressPolicy metadata: name: anthropic-managed-agents namespace: kagent spec: destinations: - origin: "https://*.anthropic.com" --- apiVersion: api.kagent.dev/v1alpha3 kind: SandboxTemplate metadata: name: claude namespace: kagent spec: workload: # Experimental tools image from the blog, including the ant CLI. image: ghcr.io/kagent-dev/kagent/sandbox-guest@sha256:94b1f9e216eee8778797d54b9d6e2b17b74089157d708097577b1479e4d92bd0 substrate: workerPoolRef: name: kagent-default snapshotPolicy: location: s3://ate-snapshots/kagent/ egressPolicyRefs: - name: anthropic-managed-agents EOFFor wildcard matches to Anthropic, use the quoted YAML value
"https://*.anthropic.com"as shown. A destination that injects a credential must use an exact hostname instead of a wildcard. For the accepted forms, see Origin format and limits.The workload image must contain a complete 64-character SHA-256 digest, such as the example.
Wait until the template is ready.
kubectl wait -n kagent --for=condition=Ready sandboxtemplate/claude --timeout=15m
Turn on the launcher
Store the environment key in a Secret in the controller’s namespace.
kubectl create secret generic anthropic-environment-key -n kagent \ --from-literal=key="${ANTHROPIC_ENVIRONMENT_KEY}"Create
anthropic-launcher-values.yaml. The shell substitutes the$ANTHROPIC_ENVIRONMENT_IDthat you exported in the previous steps. If your release already setscontroller.env, include those entries in this file before upgrading: Helm replaces the list rather than appending to it.cat > anthropic-launcher-values.yaml <<EOF controller: env: - name: EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_ENABLED value: "true" - name: EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_ENVIRONMENT_ID value: "$ANTHROPIC_ENVIRONMENT_ID" - name: EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_ENVIRONMENT_KEY valueFrom: secretKeyRef: name: anthropic-environment-key key: key - name: EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_TEMPLATE_NAMESPACE value: kagent - name: EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_TEMPLATE_NAME value: "claude" EOFUpgrade the existing Helm release. Use the same experimental chart version that you installed, as shown by
helm list -n kagent.export KAGENT_CHART_VERSION=$(helm list -n kagent -o json \ | jq -er '.[] | select(.name == "kagent") | .chart | ltrimstr("kagent-")') helm upgrade kagent \ oci://ghcr.io/kagent-dev/kagent/helm/kagent \ --namespace kagent --version "$KAGENT_CHART_VERSION" \ --reuse-values -f anthropic-launcher-values.yaml --waitVariable Description EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_ENABLEDSet to trueto start the launcher. When the value is omitted orfalse, the launcher stays off and the other variables are ignored.EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_ENVIRONMENT_IDRequired. The Anthropic environment whose work the launcher claims. EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_ENVIRONMENT_KEYRequired. The environment key, which the launcher uses to poll for work and to send heartbeats. The controller does not pass it into any Sandbox. EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_TEMPLATE_NAMESPACERequired. The namespace of the SandboxTemplate. EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_TEMPLATE_NAMERequired. The name of the SandboxTemplate. EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_BASE_URLOptional. An override for the Anthropic API endpoint, for both the launcher and the worker. The value must be an httporhttpsURL without credentials, a query, or a fragment.EXPERIMENTAL_ANTHROPIC_SELF_HOSTED_SANDBOXES_TTLOptional. The lifetime of each Sandbox, which is also the timeout of its worker. Defaults to 12h. The value is a positive duration, such as2h30m, and the installation’s maximum Sandbox lifetime still applies.If the configuration is invalid, the controller logs an error and starts without the launcher.
Check the controller logs for errors from the launcher.
kubectl logs -n kagent deployment/kagent-controller | grep -i "anthropic self-hosted"
Run a Claude Session
Create a Claude Managed Agent, and save its ID.
AGENT_ID=$(ant --format json beta:agents create \ --name "kagent-sandbox-agent" \ --model claude-haiku-5-5 \ --system "You are a coding agent. Your working directory is /data/workspace. Be concise." \ --tool '{type: agent_toolset_20260401}' | jq -r .id)Create a Session for the agent in your self-hosted environment.
SESSION_ID=$(ant --format json beta:sessions create \ --agent "$AGENT_ID" \ --environment-id "$ANTHROPIC_ENVIRONMENT_ID" | jq -r .id)Connect to the Session.
ant beta:sessions connect "$SESSION_ID"Ask the agent to create a file, such as
/data/workspace/helloworld.txtthat containsHello world!.> Write a file /data/workspace/helloworld.txt that says, "Hello world!"In the
antterminal session, you can see thekagent-sandbox-agentwrite the file. The launcher claims the work and creates a Sandbox namedanthropic-<session-id>from theclaudetemplate. The agent’s tool calls run in that Sandbox. You see a response similar to the following:I created `/data/workspace/helloworld.txt` containing `"Hello world!"` followed by a newline.After 5 minutes without work, the worker exits and kagent suspends the Sandbox. In the Claude Console, the status becomes Idle.
Ask the agent to read the file back. kagent resumes the Sandbox, and the file is still there.
> Read me the contents of /data/workspace/helloworld.txtExample output:
The file contains: Hello world!Ask the agent to fetch a page from a destination that the EgressPolicy does not allow. The request fails, because the Sandbox cannot reach that destination.
> Use wget to tell me about kagent.devExample output:
wget can't reach kagent.dev from this environmentNote that if the session has access to other tools, such as Claude’s
web_searchorweb_fetch, the agent might fall back to use those allowed tools. The EgressPolicy prevents access only for the tools that run in the kagent Sandbox, not in the Claude environment.
View the Sandboxes
The launcher creates each Sandbox under its own identity, not yours, so kagent sandbox list does not show them. In an installation without authentication, the --user-id flag selects the identity to list as. The launcher’s identity combines the kagent:anthropic-self-hosted-sandboxes authority with your environment ID, each encoded in URL-safe base64 without padding.
USER_ID="$(printf '%s' 'kagent:anthropic-self-hosted-sandboxes' | base64 | tr '+/' '-_' | tr -d '=\n')"
USER_ID="${USER_ID}.$(printf '%s' "$ANTHROPIC_ENVIRONMENT_ID" | base64 | tr '+/' '-_' | tr -d '=\n')"
kagent sandbox list --user-id "$USER_ID"Example output:
ID TEMPLATE STATE OPERATION EXPIRES FAILURE
01a1b853-xxx kagent/claude RUNTIME_STATE_SUSPENDED RUNTIME_OPERATION_NONE 2026-11-08T11:24:07Z
Run more than one controller replica
Only the leader controller replica polls Anthropic and launches workers. When leadership moves to another replica, the new leader finds the existing Sandboxes by name and continues to use them. The chart sets controller.terminationGracePeriodSeconds to 180 by default, so that a launch that is in progress can finish before the leader releases its lease. Workers that are already running continue in their Sandboxes while leadership changes.