Self-Hosted Sandbox: Seven Production Patterns for 2026

Anthropic's self-hosted sandbox capability — shipped in public beta at Code with Claude London on May 19, 2026 — lets teams run Claude Managed Agents with tool execution inside their own infrastructure perimeter: their containers, their filesystems, their network egress rules. The orchestration layer stays with Anthropic; what moves is the surface where code runs and data is written. This guide extracts seven production patterns from Anthropic's Agent SDK docs, the MCP tunnels overview, and the secure deployment guide, paired with honest maturity ratings and the gaps that most launch coverage did not mention.

The stakes are not hypothetical. Every enterprise team evaluating Claude Managed Agents for regulated workloads faces the same questions: where does the agent's code execute? Who controls the credential surface? What happens to the audit trail? Can a prompt-injection attack exfiltrate an API key? Self-hosted sandboxes answer the first question; the remaining six patterns address the rest. Each pattern in this guide comes with a “when to use” and a “when NOT to use” — because the platform is new enough that the wrong deployment pattern will cost more in operational overhead than it saves in capability.

This guide covers the architecture anatomy of self-hosted sandboxes and MCP tunnels, then moves through all seven patterns with code skeletons sourced from primary Anthropic documentation. It closes with a proprietary Pattern Maturity Matrix — the only published piece that rates all seven patterns across four axes simultaneously — and an honest accounting of the three gaps that most launch coverage glossed over. For the announcement news itself, see the companion post Code with Claude London: Sandboxes and MCP Tunnels launch.

Code with Claude London was the second of three 2026 Anthropic developer conference stops (San Francisco May 6, London May 19, Tokyo June 10). Managed Agents PM Jess Yan and member of technical staff Lance Martin presented the two May 19 additions to the Managed Agents platform. Both are additions to the Managed Agents product — not standalone releases and not part of the Claude Code SDK or Claude API directly.

Two features shipped simultaneously. First, self-hosted sandboxes (public beta): “moves tool execution into infrastructure you control, so the agent's code, filesystem, and network egress never leave your environment,” per the Anthropic Managed Agents docs. Second, MCP tunnels (research preview): “outbound-only connection, so you don't need to open inbound firewall ports, expose services to the public internet, or allowlist Anthropic's IP ranges,” per the MCP tunnels overview. Both require the beta header on API calls: anthropic-beta: managed-agents-2026-04-01.

Two critical limitations were disclosed at launch but received little attention in coverage. First, self-hosted sandboxes are not yet available on Claude Platform on AWS — teams operating in AWS-hosted Claude environments cannot use this feature yet. Second, memory is not yet supported with self-hosted sandboxes — the cross-session memory capability available in Managed Agents cloud sessions does not extend to the self-hosted configuration. Both limitations are documented in the Anthropic platform docs and should be evaluated before committing to a self-hosted architecture for stateful long-running agents.

Understanding the architecture boundary is the prerequisite for all seven patterns. The Managed Agents platform has two distinct planes: the orchestration plane (always on Anthropic's infrastructure) and the execution plane (in self-hosted mode, on your infrastructure). A misconception that appears in some coverage is that self-hosted sandboxes mean a fully on-premise deployment — they do not. The-decoder's coverage was explicit: “A fully on-premise deployment of the agents isn't possible.” Anthropic's orchestration, session routing, and the Claude model itself remain cloud-side.

The environment worker is the process you run inside your infrastructure. It claims items from a session queue, spawns an execution context for each session (your container, VM, or serverless function), downloads the agent's skills to /workspace/skills/<name>/, runs tool calls locally, and posts results back to the Managed Agents queue. The worker receives five environment variables per session from Anthropic: ANTHROPIC_SESSION_ID, ANTHROPIC_ENVIRONMENT_KEY, ANTHROPIC_WORK_ID, ANTHROPIC_ENVIRONMENT_ID, and ANTHROPIC_BASE_URL. These are the identity tokens for each isolated session — never share them across sessions.

Two worker dispatch modes are available. The always-on worker continuously polls the session queue — appropriate for high-volume deployments where sub-second dispatch latency matters. The webhook-triggered handler wakes on session.status_run_started events — appropriate for cost-sensitive or bursty workloads where you want to pay only for active session time. The worker liveness window is 30 seconds: a worker that has not polled in the last 30 seconds is marked unhealthy. MCP tunnels connect your private-network MCP servers to the Managed Agents platform via cloudflared, requiring outbound TCP and UDP on port 7844 to the Cloudflare edge range 198.41.192.0/19.

The container-per-session pattern is the foundation of self-hosted sandbox security. Each agent session gets its own isolated container with a pinned image, dropped capabilities, read-only root filesystem, and no network egress. The Anthropic Agent SDK secure deployment guide publishes the canonical hardening recipe, which combines Docker flags with an optional gVisor or Firecracker runtime for deeper isolation.

Image pinning is not enforced by the Managed Agents platform — the docs show ARG ANT_VERSION=1.9.1 to pin the CLI version, but the broader image digest pinning is your responsibility. In production, tag images by SHA digest, not by mutable tags like :latest. A mutable tag in a spawn script means a supply chain compromise can silently alter the agent runtime without any indication in your audit logs. The SDK helper dependencies are explicit about requirements: /bin/bash must exist at that exact path; the TypeScript SDK additionally requires unzip, tar, and Node.js 22 or later.

For workloads requiring stronger syscall isolation beyond Docker namespaces, Anthropic documents two options: gVisor (--runtime=runsc) intercepts syscalls in userspace and has 0% overhead for CPU-bound work but 2-200x overhead for file-I/O-intensive operations; Firecracker microVMs provide a dedicated kernel per session with under 125ms boot time and under 5 MiB overhead. Choose based on your tool-call profile: gVisor fits compute-heavy agents, Firecracker fits agents with heavy filesystem writes. For the broader sandboxing taxonomy across Docker, microVMs, and self-hosted modes, see our companion post on AI agent sandboxing isolation patterns.

When to use. Every multi-session deployment that handles customer data, writes to a filesystem, or makes network calls. Container isolation is the minimum viable security posture for self-hosted sandboxes in any environment beyond solo developer prototyping.

When NOT to use. Single-user development prototyping — the overhead of building and pinning a container image slows iteration without meaningful security benefit when only one trusted developer is running sessions. Start with the in-process worker for dev; add container isolation before staging.

# spawn.sh — per-session container launch
# Source: platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes

docker run --rm \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --read-only \
  --tmpfs /tmp:size=100m \
  --tmpfs /home/agent:size=500m \
  --network none \
  --memory 2g \
  --cpus 2 \
  --pids-limit 100 \
  --user 1000:1000 \
  -e ANTHROPIC_SESSION_ID="$SESSION_ID" \
  -e ANTHROPIC_ENVIRONMENT_KEY="$ENV_KEY" \
  -e ANTHROPIC_WORK_ID="$WORK_ID" \
  -e ANTHROPIC_ENVIRONMENT_ID="$ENV_ID" \
  -e ANTHROPIC_BASE_URL="$BASE_URL" \
  your-org/agent-worker:sha256-<digest>  # pin by digest, never :latest

MCP tunnels provide three independent cryptographic layers. The outer layer is mTLS between Anthropic and the Cloudflare transport edge. The inner layer is TLS between the Anthropic backend and your reverse proxy. The third layer is OAuth on each upstream MCP server. This layering means a compromise of any single layer does not immediately expose your MCP server payloads — but the MCP tunnels security warning is explicit: “If an attacker obtains your tunnel token and one of your TLS private keys, they could impersonate your proxy and read MCP request payloads. Treat both as high-value secrets.”

Anthropic's recommended programmatic-access path is Workload Identity Federation (WIF). WIF requires an OIDC issuer and a federation rule scoped to org:manage_tunnels. This eliminates static tunnel tokens as a credential surface — the tunnel identity is derived from your workload identity provider at runtime. The manual fallback (static tunnel token plus a registered CA cert) remains available and is appropriate for initial setup and troubleshooting, but should not be the production path. Stacklok offers a partner integration that adds Okta, Entra, or Google Workspace IdP gating in front of virtual MCP — “install once, use everywhere” is their framing. That is the partner's commitment, not Anthropic's. For the broader MCP server security framework, see our MCP Server Security Best Practices: 2026 Engineering Guide.

When to use. Any MCP server that contains proprietary data, authenticates to internal APIs, or accesses private-network services that should not be reachable from the public internet. This is the primary use case: private Slack bots, internal databases, enterprise search endpoints, private code repositories.

When NOT to use.Public-internet MCP servers (use the standard MCP connector — no tunnel overhead needed); pre-production tinkering where the no-availability-commitment transport is acceptable for dev but not for a demo to a customer. MCP tunnels are explicitly described as “provided as-is without any uptime, support, or continuity commitment.”

# WIF-authenticated tunnel setup (recommended path)
# Source: platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview

# 1. Configure your OIDC issuer with org:manage_tunnels scope
# 2. Create a tunnel using the WIF identity (no static token stored)
ant tunnels create \
  --auth workload-identity \
  --oidc-issuer https://your-idp.example.com \
  --mcp-server-url https://internal-mcp.example.com

# Network requirements for cloudflared
# Outbound: port 7844 TCP + UDP to 198.41.192.0/19 (+ IPv6: 2606:4700:a0::/44)
# No inbound firewall ports needed

The vault-and-proxy pattern is Anthropic's answer to the credential exfiltration risk in agentic systems. The principle: resource access tokens are never stored inside the sandbox where the agent runs. A prompt-injection attack that tricks the agent into printing its environment variables cannot succeed if those variables never hold the actual credential — they hold a scoped reference that the proxy exchanges for the real token on each outbound request, with the real token held in memory only for the minimum duration required.

Vercel Sandbox implements this at the platform level: “the environment key never enters the VM: Vercel Sandbox's credential brokering injects it on outbound requests scoped to this session,” per the Vercel Knowledge Base. This is the cleanest implementation of the pattern because the brokering happens at the infrastructure layer, invisible to the agent runtime.

The gap worth naming explicitly: Anthropic does not publish a first-party credential vault primitive. The vault-and-proxy pattern is a responsibility model — Anthropic enforces the principle but not the implementation. You bring HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, or a partner-managed service. Compare this to Microsoft Copilot Studio, which shipped native Azure Key Vault integration at computer-use GA on May 13, 2026: agents reference a credential asset stored in Azure Key Vault with just-in-time retrieval and in-memory-only handling. Anthropic does not have a matching built-in primitive today. For the cross-platform comparison of how Anthropic, Microsoft, and Google handle credential injection in computer-use agents, see our analysis of computer-use agents across platforms.

When to use. Any agent that needs to call authenticated APIs, sign in to web UIs, or access databases. This is not optional for production deployments — it is the baseline security posture against prompt injection as an exfiltration vector.

When NOT to use. Pure read-only public-data agents that make no authenticated calls — the overhead of a vault proxy adds latency and operational complexity for no security benefit.

Human-in-the-loop approval gates are the most operationally mature pattern in this list. The Agent SDK ships with 19 hook events across Python and TypeScript SDKs, including PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStart, SubagentStop, PermissionRequest, and Notification. The primary HITL gate is PreToolUse: it fires before any tool call executes and accepts a permission decision of "allow", "deny", "ask", or "defer". Multiple hooks can run in parallel; precedence is: deny over defer, defer over ask, ask over allow.

The defer decision is the canonical interrupt-and-resume pattern. When a hook returns defer, the query ends cleanly — the session is not destroyed, it is suspended. You can then deliver the pending decision out-of-band (via a Slack message, a webhook, or a PagerDuty alert) and resume the session when the human approves or denies. The Notification hook fires on permission_prompt, idle_prompt, and other operational events — forward these to your team's alerting channel so that a deferred approval does not sit unreviewed. Per the Agent SDK hooks docs, deny always wins — if any hook in a parallel set returns deny, the tool call is blocked regardless of what other hooks return.

When to use. Production writes to databases, file systems, or external APIs; regulated workflows where an audit trail of human decisions is required (financial, legal, healthcare); any reversible-but-painful operation where the cost of an incorrect action is high enough to warrant human review on each execution.

When NOT to use. Read-only research agents — the latency overhead of a hook callback plus a human review window kills the utility of an agent that is simply fetching and summarizing information. Route HITL gates on tool-call type: mcp__*_write and bash_execute get gated; mcp__*_read and web_search do not.

// PreToolUse hook — HITL approval gate
// Source: code.claude.com/docs/en/agent-sdk/hooks

import { Hook, PermissionDecision } from "@anthropic-ai/claude-agent-sdk";

const hitlGate: Hook = {
  event: "PreToolUse",
  async handler({ tool_name, tool_input }) {
    const writeTools = ["bash", "str_replace_editor", "file_write"];
    if (!writeTools.includes(tool_name)) {
      return { hookSpecificOutput: { permissionDecision: "allow" } };
    }

    // Forward to Slack / webhook for human review
    const pending = await enqueueForHumanReview({ tool_name, tool_input });

    // Return defer — session suspends; resume when decision arrives
    return {
      hookSpecificOutput: {
        permissionDecision: "defer",
        permissionDecisionReason: `Pending review: ${pending.id}`,
      },
    };
  },
};

Regression testing for Claude agents does not yet have a single canonical toolchain — the ecosystem is stabilizing around two tracks. The community standard is promptfoo with the anthropic:claude-agent-sdk provider, which authenticates through a local Claude Code session (apiKeyRequired: false) and integrates directly with the Agent SDK. Promptfoo is used by OpenAI and Anthropic internally per the project's own documentation, which gives it credibility as the de facto external eval framework for Agent SDK workloads.

On the Anthropic platform side, self-evaluation loops are a Managed Agents research-preview feature: you define outcomes and success criteria, and Claude iterates internally. This is promising for agents with well-defined correctness criteria (code that compiles and passes tests, SQL that returns the expected row count) but is not yet appropriate for agents whose success criteria require human judgment. TribeAI publishes a claude-evals open-source framework with a 50-case golden dataset and SDK hook integration — worth reviewing as a starting template if you are building a CI eval suite from scratch.

The architecture recommendation: run promptfoo evals on your golden dataset in CI as a PR gate. Any commit that changes tool descriptions, system prompts, or skill configurations triggers the eval suite. A regression on a golden case fails the PR. This pattern catches prompt drift and tool-schema changes before they reach production sessions. For more on migrating from the Claude Code SDK to the Agent SDK, the migration playbook covers eval suite re-integration as one of its core steps.

When to use. Every production agent — a regression suite in CI is not optional for agents that make writes or call authenticated APIs. Even a 20-case golden dataset catches the most common regression patterns from prompt changes.

When NOT to use.Hackathon demos and one-off research assistants where the agent's behavior is wholly exploratory and user-driven — UX testing covers the correctness surface adequately.

# promptfoo config — Claude Agent SDK provider
# Source: promptfoo.dev/docs/providers/claude-agent-sdk

providers:
  - id: anthropic:claude-agent-sdk
    config:
      apiKeyRequired: false  # authenticates via local Claude Code session
      model: claude-opus-4-6
      max_turns: 10

tests:
  - description: "Correctly identifies and flags PII in CSV"
    vars:
      input: "{{file://test-data/pii-sample.csv}}"
    assert:
      - type: contains
        value: "PII detected"
      - type: not-contains
        value: "Error"

The Agent SDK CLI ships with OpenTelemetry instrumentation built in, making audit log shipping the most operationally mature pattern in this list with the lowest custom-code overhead. Enable it via CLAUDE_CODE_ENABLE_TELEMETRY=1 plus the standard OTEL_* exporter environment variables. Add CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 for richer span attributes during the beta period. Per the Agent SDK observability docs, the SDK emits a four-level span hierarchy: claude_code.interaction at the root, with child spans for claude_code.llm_request, claude_code.tool, and claude_code.hook. Metrics include token counts, cost, and session counts. Default flush intervals: traces and logs every 5 seconds, metrics every 60 seconds.

W3C trace-context propagation is automatic: the SDK injects TRACEPARENT and TRACESTATEinto the CLI subprocess, so agent runs nest inside your application's existing distributed trace. If your application already emits spans to Datadog or Honeycomb, agent sessions appear as child spans in the same trace view. Datadog ships Claude Code Monitoring in its AI Agents Console — if you are already on Datadog, this is the fastest path to a production audit dashboard.

For per-user SIEM-grade audit trails, tag end-user identity in the OTel resource attributes: OTEL_RESOURCE_ATTRIBUTES=enduser.id=...,tenant.id=... (percent-encode values). The resulting events — tool_decision, tool_result, mcp_server_connection, permission_mode_changed — form a per-user audit trail that meets the data completeness requirements of most regulated sector compliance frameworks. This pairs directly with the AI transformation advisory work we do with compliance-sensitive clients.

When to use. Every production deployment. This is not optional — observability is the minimum viable operational posture for any agent that makes writes or authenticated API calls. The three-environment-variable enablement cost is negligible relative to the operational blind spot created by running without it.

When NOT to use. There is no valid reason to skip OTel telemetry in production. For dev environments, disable it to reduce noise: leave CLAUDE_CODE_ENABLE_TELEMETRY unset.

# Agent SDK — OpenTelemetry telemetry enablement
# Source: code.claude.com/docs/en/agent-sdk/observability

# Required
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# Enhanced spans (beta — richer tool_decision + permission_mode_changed events)
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1

# Exporter — send to Datadog OTLP endpoint
export OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.datadoghq.com
export OTEL_EXPORTER_OTLP_HEADERS="DD-API-KEY=<your-api-key>"

# Per-user audit trail tagging (percent-encode special chars)
export OTEL_RESOURCE_ATTRIBUTES="enduser.id=user-123,tenant.id=org-456"

# Flush intervals: traces + logs = 5s, metrics = 60s (defaults)
# W3C trace-context: TRACEPARENT injected automatically into CLI subprocess

Managed Agents handles checkpointing automatically for cloud sessions: long-running sessions checkpoint after major tool steps so that a network blip does not restart a two-hour task from zero. The /resumeendpoint re-attaches to a checkpointed session. The $0.08 per session-hour runtime charge covers “tool-call compute, checkpointing, and recovery” — the checkpointing infrastructure is included in the runtime price, not an add-on.

Graceful session termination uses work.stop — this signals the agent to complete its current tool call and then stop cleanly. Pass force: true to interrupt mid-tool-call when a session must be terminated immediately (e.g., a HITL deny decision on a long-running tool). For rollback scenarios, the pattern is: checkpoint before any write operation, capture the session state token, execute the write, and if the write fails or is denied, restore to the pre-write checkpoint. This is an application-level pattern — Managed Agents provides the checkpoint primitive but not the transactional rollback logic.

The gap to name explicitly: memory is not yet supported with self-hosted sandboxes. Cross-session state — remembering what a user has asked across multiple sessions, maintaining a workspace that persists between runs — is available in Managed Agents cloud sessions but does not extend to self-hosted configurations. For self-hosted deployments that need cross-session state, you must roll your own: write state to an external store (Redis, PostgreSQL, S3) at the end of each session and restore it at the start of the next. This is a meaningful operational overhead that should factor into the decision to use self-hosted versus cloud-hosted sandboxes.

When to use. Long-running agents with multi-hour tasks — research pipelines, large codebase refactors, multi-step operations automations. The $0.08/hour runtime cost is the cheapest way to get durable session state for cloud-hosted sessions.

When NOT to use. Short single-turn agents where each session completes in under 60 seconds — the checkpointing overhead is noise. Self-hosted sandboxes with cross-session state requirements until the memory limitation is lifted.

No published launch coverage compares all seven patterns across Anthropic native support, MCP extensibility, custom-code requirement, and maturity simultaneously. The “Maturity” column is the most load-bearing — most coverage conflates “announced” with “GA,” which leads teams to build against research previews as if they carry production-level SLAs. The matrix below is sourced from the primary Anthropic docs cited throughout this guide.

Most launch coverage of self-hosted sandboxes presented the feature as a complete enterprise security solution. It is a significant step toward that — but three specific gaps should determine your architecture decision before you commit to a self-hosted deployment.

Gap 1: Not available on Claude Platform on AWS. Teams operating Claude through Anthropic's AWS-hosted platform cannot use self-hosted sandboxes yet. This eliminates the feature for any organization whose Claude access is routed through the AWS marketplace or enterprise agreement. Check your Anthropic account configuration before designing a self-hosted sandbox architecture.

Gap 2: Memory not supported in self-hosted mode. Cross-session agent memory — the ability for an agent to remember context across separate sessions — is not supported in self-hosted sandbox configurations. Cloud-hosted Managed Agents sessions have this capability; self-hosted does not. For any agent that needs to maintain workspace state across multiple user interactions, you must implement external state management and cannot rely on the Managed Agents memory primitive.

Gap 3: No first-party credential vault primitive. As covered in Pattern 3, the vault-and-proxy pattern is Anthropic's recommendation but not a managed service. Building and operating a credential proxy adds operational overhead that a managed service would eliminate. Until Anthropic ships a native vault primitive, teams with limited infrastructure engineering capacity are better served by Vercel Sandbox's built-in credential brokering or by staying on cloud-hosted Managed Agents where the credential exposure surface is smaller.

When not to use self-hosted sandboxes at all. If your organization has no existing container orchestration infrastructure, starting with self-hosted sandboxes adds a substantial operational layer before your first production agent. Cloud-hosted Managed Agents — with the HITL hooks, OTel telemetry, and checkpoint patterns from this guide — address the majority of enterprise security requirements without the infrastructure overhead. Come back to self-hosted when your team has container-per-session deployment in their operational playbook. For a security audit checklist covering both deployment modes, see our 75-point MCP server security audit checklist.