Agent Sandbox Architecture: How to Choose the Right Runtime Boundary

AI agents are starting to need computers of their own.

That sounds dramatic, but the architecture shift is simple. Once an agent can write code, run shell commands, edit files, install packages, inspect outputs, and keep working across sessions, a plain tool call is not enough. You need a runtime boundary around the work.

That boundary is the sandbox.

The question is no longer whether sandboxes matter. The question is which sandbox shape fits the job.

Last updated: June 23, 2026

Why This Is Timely

LangChain's recent guide on choosing the right sandbox for AI agents puts the risk plainly: agent-written code can create threats to data and systems, so teams need to control where code runs and what it can access. The post calls sandboxes computers your agent can safely use.

OpenAI's Agents SDK docs now route builders toward sandbox agents when work needs files, commands, packages, snapshots, mounts, or provider links. The TypeScript sandbox-agent docs describe persistent workspaces where agents can search document sets, edit files, run commands, generate artifacts, and resume from saved sandbox state.

Flue's repo frames the same category from another angle: a sandbox agent framework where agents can keep context, use tools, modify files, and complete real work in a secure environment. That puts it in the same practical lane as the agent harness question in Flue: Agent Harness Framework, Different or Just Shiny?.

The trend is clear: sandboxing is becoming agent backend infrastructure.

The Take: A Sandbox Is Not Just a Container

The lazy version of sandboxing is "run it in Docker."

That may be part of the answer. It is not the whole answer.

A useful agent sandbox answers seven questions:

If your sandbox only isolates processes but leaves secrets, network, logs, and snapshots vague, you still have a weak agent runtime.

For the broader team-control-plane layer, read Sandboxed Agents Are Becoming the Team Control Plane. This piece is the lower-level architecture guide.

The Agent Lethal Trifecta

LangChain uses a useful security frame: agents become risky when three ingredients combine.

1. They can access private data.
2. They can receive untrusted instructions.
3. They can exfiltrate data or take actions.

That is the agent version of the lethal trifecta.

The sandbox should break at least one side of that triangle. Ideally, it weakens all three:

• only mount the files the task needs;
• treat web pages, issues, docs, and customer messages as untrusted inputs;
• block broad outbound network access;
• inject credentials after the sandbox boundary instead of placing them inside it;
• log every file, command, and network-relevant action.

This is why "just ask the model not to leak secrets" is not a security control. The model may be tricked. The sandbox should make the trick less useful.

Local vs Cloud Sandboxes

The first architecture choice is where the sandbox lives.

There is no universal winner.

A docs summarizer probably does not need a shell. A code migration agent probably does. A security triage agent may need an isolated workspace with no outbound network except approved package mirrors. A customer support agent may need no filesystem at all.

The architecture should follow blast radius, not ambition.

The Secrets Boundary Is the Real Test

The most important sandbox design question is where credentials live.

If secrets are mounted as plain files or environment variables inside the sandbox, untrusted code can try to read and leak them. That may be acceptable for a throwaway API key in a toy demo. It is not acceptable for production systems.

LangChain's sandbox post describes an authorization-proxy pattern: credentials get injected into outbound traffic after it leaves the sandbox, so untrusted code inside the sandbox does not directly hold the secret.

That is the shape teams should copy.

The policy:

Do not put durable production credentials inside an agent sandbox.
Give the sandbox scoped capabilities.
Inject credentials at a controlled boundary.
Log which capability was used, not only which command ran.

For coding-agent workflows, pair this with Permissions, Logs, and Rollback. Permissions without logs are weak. Logs without rollback are a documentary.

Snapshots Matter More Than People Expect

OpenAI's sandbox-agent docs emphasize saved sandbox state and snapshots. That is not a minor convenience.

Snapshots solve three practical problems:

Resume. Long-running work can continue from the same files, packages, and generated artifacts instead of rebuilding context from scratch.

Rollback. A bad edit, bad package install, or bad generated artifact can be compared against a previous state.

Review. The team can inspect what the agent actually had in its workspace when it made a decision.

Without snapshots, a failed agent run is often unreproducible. You have logs, but not the state those logs refer to.

That connects directly to agent workflows as code. If a workflow has typed gates, the sandbox snapshot is one of the receipts those gates should preserve.

When Shell Access Is Overkill

Not every agent needs a computer.

Giving an agent shell and filesystem access increases capability, but it also increases attack surface. Before adding a sandbox, ask whether the agent can do the job with narrower tools:

• database query tool with read-only access;
• document retrieval;
• structured API calls;
• file search only;
• code interpreter without network;
• domain-specific function tools;
• human approval before writes.

If a narrow tool solves the workflow, use the narrow tool.

Reach for a general sandbox when the agent genuinely needs to create or transform artifacts over multiple steps: code patches, notebooks, generated files, package experiments, build outputs, data analysis scripts, or long-running project work.

That is the difference between useful autonomy and unnecessary blast radius.

A Decision Checklist

Before choosing a sandbox provider or framework, answer these questions:

1. Does the agent need a filesystem, or only structured tools?
2. Which files should be mounted by default?
3. Is outbound network blocked, allowlisted, or open?
4. Are secrets inside the sandbox, or injected at a proxy boundary?
5. Can the sandbox snapshot and resume state?
6. What CPU, memory, disk, and time limits apply?
7. Are logs and artifacts retained for review?
8. Can humans approve risky actions before they happen?
9. Can the run be reproduced from a snapshot?
10. Can the sandbox be self-hosted if policy requires it?

If a vendor cannot answer those clearly, do not treat it as production-grade yet.

The Opposing Take: Most Agents Should Stay Narrow

The counterargument is strong: sandboxes are infrastructure, and infrastructure has cost.

Many useful agents do not need general code execution. A support agent can answer from retrieved documents. A sales agent can draft follow-ups from CRM fields. A release-note agent can summarize merged pull requests. A documentation agent can propose edits through a narrow patch tool. That is also why the managed-agent decision in Managed Agents vs LangGraph vs DIY should start with the runtime boundary, not the marketing category.

For those agents, a full sandbox may be ceremony.

The better default is least capability:

• start with narrow tools;
• add file access only when needed;
• add shell only when command execution is central to the job;
• add network only when the task proves it needs it;
• keep snapshots and logs whenever stateful work begins.

Sandboxes are powerful because they let agents do real work. That is also why they should not be handed out casually.

FAQ

What is an AI agent sandbox?

An AI agent sandbox is an isolated runtime where an agent can work with files, commands, packages, tools, and artifacts without directly touching the host system or production environment. A good sandbox also controls network access, credentials, resource limits, snapshots, and logs.

Is Docker enough for agent sandboxing?

Docker can be part of a sandbox, but it is not sufficient by itself. You still need filesystem scoping, network policy, secrets handling, resource limits, snapshots, logs, and approval gates.

When does an agent need shell access?

An agent needs shell access when the task depends on running commands, installing packages, executing tests, transforming files, or generating artifacts. If the task can be handled through narrow structured tools, avoid shell access.

Where should secrets live in an agent sandbox?

Prefer keeping durable secrets outside the sandbox and injecting scoped credentials at a controlled boundary, such as an authorization proxy. Avoid placing production credentials directly into files or environment variables that untrusted code can inspect.

What should I log from sandboxed agent runs?

Log the task contract, mounted files, allowed tools, commands, file changes, network-relevant actions, approvals, snapshots, verification output, cost, latency, and final receipt. The goal is to make the run reproducible and reviewable.

Sources

• LangChain: How to Choose the Right Sandbox for AI Agents
• OpenAI API Docs: Agents SDK
• OpenAI Agents SDK TypeScript: Sandbox agents
• GitHub: withastro/flue
• Hacker News: Build and Host AI apps on your own servers