If you want to let Claude Code work on a real codebase, run code, and use tools on behalf of a user, you quickly run into a trust problem.
It is not enough to say "the agent runs in a sandbox." You also need to decide which part of the system is trusted, which part is not, and where secrets are actually allowed to live.
That is what this runtime is built around.
In practice, there are five questions that matter:
- Where do the files live?
- Where does generated code actually run?
- How does the model reach Anthropic or OpenRouter?
- How do tools and MCP integrations work?
- Which process is trusted, and which one is not?
This article walks through those questions one by one.
The Basic Shape of the Runtime
Each session gets its own sandboxed environment. Inside that sandbox, the actual Claude Code process runs in a separate execution container.
By that we mean the agent process does not run directly on the sandbox host and it does not run in the same process as the Sandbox Manager. In our case, the execution container is the inner Docker container where Claude actually runs commands, executes scripts, installs packages, and works against the mounted workspace.
We also add gVisor through Docker with runsc. In plain language, that gives the container one more isolation layer instead of relying only on a standard container boundary. If the agent process misbehaves, that extra boundary matters.
Next to that container sits a trusted control layer we call the Sandbox Manager. It prepares the session, starts the agent process, manages tools and MCP calls, and controls the paths that lead to secrets and model access.
So there are really two boundaries that matter:
- the agent process, which is the untrusted part
- the Sandbox Manager, which is the trusted part
Where the Files Live
Project files are first prepared on the sandbox host side. The Sandbox Manager creates the workspace there and writes the runtime files the session needs before the agent starts.
That workspace is then bind-mounted into the inner execution container as the agent's working directory. So the agent sees the real project through a mounted workspace, not through a copied snapshot that can drift out of sync.
This is important because it tells you both what the agent can do and where it is doing it.
The agent can:
- read files
- edit files
- create new files
- run code from those files
But it is still doing all of that from inside the isolated container.
So if the agent writes a script into the workspace and executes it, that code runs inside the container, not on the sandbox host.
What Actually Runs Inside the Container
The agent process runs inside the inner container, not directly in the Sandbox Manager.
In practice, that means the normal things you expect from an agent session all happen inside that isolated boundary:
- shell commands
- scripts
- package installs
- code execution
The Sandbox Manager stays outside that path. It prepares the workspace, starts the agent, manages streaming, and exposes the bridge that tools and MCP integrations use.
That split is deliberate. The part that orchestrates the session is not the same part that runs the untrusted agent workload.
How Model Access Works
When Claude needs the model, it does not call Anthropic or OpenRouter directly.
Instead, the sandbox receives our own short-lived proxy token and uses that token to call our private proxy service. That proxy service then forwards the request upstream with the real provider credentials attached.
That means:
- the agent can reach the model
- the sandbox does not hold the real upstream credentials
- the real
ANTHROPIC_API_KEYand other provider keys stay on our private proxy service
So the agent process gets access to inference, but it does not get direct ownership of the provider account credentials.
How Tools and MCP Work
Tools and MCP integrations follow a different route from model inference.
The agent process does not connect to those integrations directly. Instead, tool and MCP requests go through the Sandbox Manager.
You can think of the Sandbox Manager as a host-side gateway. It starts the MCP servers on the sandbox host, keeps them running, manages them, and proxies requests from the agent container to those MCP endpoints.
That includes both local stdio MCP servers and remote MCP servers.
That means the agent does not get direct access to MCP servers at all. It asks the Sandbox Manager to make the call, and the Sandbox Manager handles that call on the trusted side.
The Sandbox Manager also injects the current environment variables for that execution and sends only the result back into the agent session.
That is an important boundary.
It means the agent can still use real integrations, but we do not have to treat the agent process like a place where tool secrets should live by default.
So What?
The short version is that we do not treat Claude Code like a normal host process with a folder and a pile of credentials.
We give it access to the workspace, but inside an isolated container.
We give it access to the model, but through a short-lived proxy token.
We give it access to tools, but through the Sandbox Manager.
And we keep the real provider keys and tool-side secrets outside the untrusted agent process.