What you will be able to do
- Run the Agent SDK in your own container and say where its session state lives
- Harden a self-hosted agent: credentials, gateways and tenant isolation
- Explain what Claude Managed Agents hosts, and how a self-hosted sandbox changes where tools run
1.Running the Agent SDK on your own infrastructure
When you deploy the Agent SDK, you operate everything: the process, the container, and the disk that session state lands on. The runtime needs Python 3.10+ for the Python SDK or Node.js 18+ for the TypeScript SDK. For most installs, both SDKs bundle a native Claude Code binary. Each query() call accepts options that shape the run. cwd pins the working directory, and max_turns (maxTurns in TypeScript) caps how many loop cycles one task can use. Where the session lives on disk is the part that matters most in production.
| State | Default location |
|---|---|
| Session transcripts | ~/.claude/projects/, or projects/ under CLAUDE_CONFIG_DIR if set |
| CLAUDE.md memory files | ~/.claude/CLAUDE.md (user tier) and the session's working directory (project tier) |
| Working-directory artifacts | The session's working directory |
Because that state sits on local disk, you decide how long it survives. For multi-turn sessions, TypeScript adds turns to an active session with streamInput(), while Python holds a session open with ClaudeSDKClient. To resume later, possibly on another host, pass resume with a session ID together with a SessionStore. A SessionStore can be an object store, a key-value store, a database or your own adapter. Its scope is narrow, though. It copies transcripts only, so CLAUDE.md files and working-directory artifacts need a shared volume or a separate sync. The subprocess writes to local disk first and forwards batches to the store. If a batch cannot be delivered, the SDK drops it, emits a mirror_error system message and carries on.
You can also run the SDK inside a sandbox. When you compare sandbox options, the docs list five things to weigh: who runs the sandbox (a sandbox-as-a-service provider or software you run yourself), cold-start latency, persistent storage, pricing model, and networking controls such as egress rules and VPC peering.
Sources1
2.Credentials, gateways and tenant isolation
A self-hosted agent is a process that runs tools, so treat it as untrusted. Credentials are handled in three places. For Anthropic API access, the subprocess reads ANTHROPIC_API_KEY from its environment. Alternatively, set ANTHROPIC_BASE_URL to route model calls through a proxy that adds the key outside the container. For inbound traffic, authentication happens at a gateway in front of the agent, not in the agent. For outbound tools, keep tool credentials out of the agent's environment entirely: the agent makes the call and a proxy adds the credential.
If one host serves several tenants, each tenant needs its own inputs. Pass an explicit per-tenant cwd on every call. Skip user, project and local settings with an empty setting-sources list. Point CLAUDE_CONFIG_DIR at a per-tenant directory so tenants don't share global config. Also disable auto memory: the empty settings list does not stop it from loading.
async def main():
async for message in query(
prompt=prompt,
options=ClaudeAgentOptions(
cwd=tenant_dir,
setting_sources=[],
env={
"CLAUDE_CONFIG_DIR": config_dir,
"CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
},
),
):
...Enforce per-tenant egress rules at your proxy as well, such as distinct outbound IPs, credentials or domain allowlists. That way a compromised tenant cannot exfiltrate data through another tenant's outbound policy. For capacity planning, the docs give a simple formula: agents per host equals host RAM minus overhead, divided by the per-session RAM ceiling.
Sources1
3.Claude Managed Agents: Anthropic hosts the harness
Everything above is work you take on when you self-host. Claude Managed Agents removes most of it. It is a pre-built, configurable agent harness running on managed infrastructure. You don't build the loop, the tool execution or the runtime. The harness includes built-in prompt caching, compaction and other performance optimisations. Built-in tools cover Bash, file operations, web search and fetch (optionally restricted by domain allowlist or blocklist), and MCP servers. Every request needs an API key and the managed-agents-2026-04-01 beta header.
| Concept | What it is |
|---|---|
| Agent | The model, system prompt, tools, MCP servers and skills; created once and referenced by ID across sessions |
| Environment | Where sessions run: an Anthropic-managed cloud sandbox or a self-hosted sandbox |
| Session | A running agent instance within an environment, performing a specific task |
| Events | Messages between your application and the agent: user turns, tool results, status updates |
You send user messages as events. Claude runs tools on its own and streams results back over server-sent events, and the event history is stored server-side. You can steer a running session with more events or interrupt it. Managed Agents fits long-running tasks that take minutes or hours, stateful sessions with persistent filesystems, scheduled cron runs, and teams that want minimal infrastructure. Its statefulness has a compliance cost, though. Because sessions store conversation history, sandbox state and outputs server-side, Managed Agents is not currently eligible for Zero Data Retention or HIPAA BAA coverage. You can still delete sessions and uploaded files through the API.
Sources2
4.Managed orchestration, self-hosted execution
Managed Agents has a middle option. By default, tools run in Anthropic-managed cloud sandboxes. A self-hosted sandbox keeps orchestration with Anthropic but runs tools on infrastructure you control. The filesystem, the processes and the network the agent can reach stay inside your environment. The connecting piece is an environment worker, a process you run. The self_hosted environment works as a work queue. Your worker claims work items by polling, downloads the agent's skills, runs the tool calls and posts the results back. The worker can poll continuously, or a webhook can wake it on session.status_run_started. The ant CLI's pre-built worker supports only the always-on pattern. The SDK's worker supports both.
| Aspect | Cloud environment | Self-hosted sandbox |
|---|---|---|
| Where tools run | Anthropic-managed sandboxes | Your infrastructure |
| Network reach | Anthropic's egress controls | Your network policy |
| File and GitHub repo mounting | Managed by Anthropic | Managed by you |
| Memory stores | Mounted by Anthropic at /mnt/memory/ | Downloaded to /mnt/memory/ and synced by the SDK worker |
| Lifecycle | Managed by Anthropic | Managed by you |
Self-hosting fits when the agent works on data that cannot leave your network, needs internal services that are not publicly routable, or must run under your own compliance and audit controls. Know its limits. Tool inputs and outputs still go to Anthropic's control plane, because that is where Claude runs. Skills and memory store contents are stored by Anthropic and copied into your sandbox. Private MCP access is a separate setting too. MCP tunnels control how Anthropic reaches MCP servers in your network, independently of where code runs.
An SRE wants an autonomous Claude Code agent to never modify secrets files. Regardless of what the system prompt tells the model, any attempt to write to a file named .env anywhere in the working tree must be rejected before it executes, and the block must hold even if a teammate later runs the same session in bypassPermissions mode. Which implementation satisfies this?
Correct answer: B — Register a PreToolUse hook matched to Write|Edit that inspects tool_input.file_path and returns permissionDecision "deny" whenever the file name is .env.
- A. A system-prompt instruction is a guideline the model can deviate from under pressure or a crafted prompt; it is not enforced by the runtime and does not guarantee the block holds in every mode.
- B. Correct. Hooks run before permission-mode evaluation and a hook's deny decision is enforced regardless of the active permission mode, including bypassPermissions, so a PreToolUse deny on the .env file name blocks the write deterministically.
- C. This scoped rule only denies the specific Bash invocation "rm .env"; it does nothing to stop the same file from being overwritten through the Write or Edit tools.
- D. Plan mode still routes file-edit attempts to the canUseTool callback for a human decision rather than guaranteeing an outright block, and the restriction disappears once the session leaves plan mode.
Sources3
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Configuring a SessionStore makes the whole session portable, including CLAUDE.md memory and files in the working directory.Why is that wrong?
SessionStore mirrors transcripts only. Memory files and working-directory artifacts need a shared volume or a separate sync.
2.Passing an empty settingSources list is enough to stop every persisted input from loading into a tenant's session.Why is that wrong?
Auto memory still loads into the system prompt. You must also set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
Covered in Credentials, gateways and tenant isolation
3.With a self-hosted sandbox, no agent data ever reaches Anthropic.Why is that wrong?
Tool execution stays on your host, but tool inputs and outputs still go to Anthropic's control plane so the model can see them.
Covered in Managed orchestration, self-hosted execution
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/agent-sdk/hostingOfficial docs
“Python 3.10+ for the Python SDK, or Node.js 18+ for the TypeScript SDK”
↩︎ Running the Agent SDK on your own infrastructure“Python: use ClaudeSDKClient to hold a session open across turns.”
↩︎ Running the Agent SDK on your own infrastructure“The agent should receive pre-authenticated requests and should not be the component that validates user tokens.”
↩︎ Credentials, gateways and tenant isolation“Route outbound calls through a proxy that injects API keys after the request leaves the container.”
↩︎ Credentials, gateways and tenant isolation“SessionStore mirrors transcripts, not CLAUDE.md memory files or other working-directory artifacts.”
↩︎ Exam trap 1“Auto memory at ~/.claude/projects/<project>/memory/ loads into the system prompt regardless of settingSources.”
↩︎ Exam trap 2 - 2.
“Instead of building your own agent loop, tool execution, and runtime, you get a fully managed environment”
↩︎ Claude Managed Agents: Anthropic hosts the harness“Managed Agents is not currently eligible for Zero Data Retention or HIPAA Business Associate Agreement (BAA) coverage.”
↩︎ Claude Managed Agents: Anthropic hosts the harness - 3.
“Self-hosted sandboxes keep the orchestration on Anthropic's side but move tool execution into infrastructure you control”
↩︎ Managed orchestration, self-hosted execution“An environment worker is a process you run on your own infrastructure.”
↩︎ Managed orchestration, self-hosted execution“Self-hosting controls where the agent's code executes. MCP tunnels control how Anthropic reaches MCP servers in your network.”
↩︎ Managed orchestration, self-hosted execution“Tool inputs and outputs still flow to Anthropic's control plane (where Claude runs) so the model can see results”
↩︎ Exam trap 3