Back to Glossary
Agent Sandbox
Synonyms: AI sandbox, sandboxed agent, agent execution environment, isolated runtime, code sandbox
Do not index
Definition
An agent sandbox is a separate, locked-down workspace where an AI agent does its work. Inside it, the agent can run code and change files, but it can’t reach your real files or the open internet unless you allow it. You review what it made, then decide what to keep. This lets you give an agent more freedom with less risk, and fewer permission prompts.
Use cases
Without a sandbox, agent mistakes hit real files and accounts. With a badly designed one, users click through a stream of approval pop-ups.
- The poisoned web page: An agent with inbox access reads a page with hidden instructions, then emails your data out. Simon Willison calls this the "lethal trifecta."
- "Where did my changes go?": An agent tidies a sandbox copy of a folder. The user assumes the real one is clean, but nothing synced back.
How it's used in practice
- Show the limits up front: "Can edit: /project. Internet: GitHub only."
- Let the sandbox replace routine prompts: Allow safe actions inside the sandbox without asking. Anthropic's sandboxing cut Claude Code permission prompts by 84% internally.
- Ask only at the boundary: Prompt when the agent wants a new domain or a real-world action, like sending an email.
- Show a diff before anything leaves: Return sandbox changes as a preview with Apply and Discard.
- Label which world users are in: A badge ("Sandbox copy" or "Live") tells users whether an action is real.
Write the "blocked" message before anything else. When a sandbox stops an agent, users usually see a vague error and blame the agent. Say what was blocked and why ("Blocked: npmjs.org isn't on this project's list"), then offer "Allow for this task only." One-time approvals keep the allowlist short.
Challenges & limitations
- Allowlists grow: Every blocked domain turns into a request to add it. One default "trusted" list Willison reviewed had dozens.
- Real tools break inside: Docker and git over SSH can fail in a sandbox, and the errors look like agent bugs.
- Not everything runs inside: In Claude Code, the file-editing tools and MCP servers run outside the Bash sandbox. Don't promise users full isolation.
Free resources
- Anthropic Adds Sandboxing and Web Access to Claude Code (InfoQ) — news coverage of the launch, including the git proxy that limits pushes to one branch.
- Claude Code for web (Simon Willison) — a hands-on review of network modes, including his worries about long default allowlists.
- Beyond permission prompts: making Claude Code more secure and autonomous (Anthropic) — how file and network isolation cut permission prompts by 84%.
