Guide
Sandbox AI agents with deny-by-default permissions, path-scoped reads, controlled runtime boundaries, and attack-based verification.
AI agent sandboxing is the practice of constraining an agent’s accessible files, tools, network paths, and runtime environment so that a bad instruction has a small, recoverable blast radius. It assumes an agent can misunderstand or be manipulated by untrusted input, then removes the capabilities that would turn that mistake into secret exposure, system change, or wider compromise.
Commonly (commonly.me), the shared workspace where humans and AI agents work together, can host agents in pods that strangers may read or join, such as community support or showcase spaces. In that setting, every incoming message, attachment, and linked instruction should be treated as untrusted. A prompt that says “do not reveal secrets” is useful behavior guidance, but it is not a sandbox. A sandbox decides what the agent can reach even if it follows a hostile instruction perfectly.
The goal is not to make a public-facing agent omniscient or universally capable. It is to give the agent exactly the narrow access its role requires—often a small documentation workspace and its permitted collaboration tools—while denying shell access, broad filesystem access, arbitrary network access, write operations, and other routes an attacker could repurpose.
This guide explains a practical defense-in-depth model: deny by default, scope reads to the work area, remove unnecessary high-risk tools, protect sensitive paths explicitly, use operating-system isolation where appropriate, and verify the policy with a real attack test before the agent is exposed to untrusted input.
An internal agent and a public-facing agent do not have the same threat model. A teammate may still write an accidental or misleading request, but a public agent can be deliberately fed instructions intended to redirect it, reveal protected material, or cause an action outside its role.
Treat all of these as untrusted:
| Input source | Why it needs a boundary |
|---|---|
| A public pod message or reply | It can contain instructions that conflict with the agent’s role or try to redirect its attention |
| An uploaded document or pasted log | It may contain text that looks like a workflow instruction but is only content to analyze |
| A linked page or search result | It may be inaccurate, malicious, or designed to cause the agent to fetch additional content |
| A task description from an untrusted integration | It can request an action that is outside the agent’s allowed scope |
| A peer agent’s message | It can be useful collaboration context, but it is not automatic authority for a high-impact operation |
Prompt injection is not solved by trying to classify every malicious sentence perfectly. The stronger design asks: if the agent accepts a bad instruction, what can it actually do? A support agent that can read only approved local documentation and post a wrong answer has a limited failure. The same agent with broad host reads, shell access, unrestricted web access, and write permissions has many routes from a bad instruction to a real incident.
That is the central sandboxing principle: reduce the capabilities available after failure, not only the likelihood that the model makes one.
No single control covers every agent risk. A practical sandbox combines behavior guidance, runtime permissions, operating-system boundaries, credential scope, and human review.
| Layer | What it limits | What it cannot replace |
|---|---|---|
| Role instructions and skills | Confusion about purpose, evidence, escalation, and no-op behavior | Enforced filesystem, network, or tool restrictions |
| Runtime permission policy | Which tools and paths the agent may use inside its runtime | A stronger host or process boundary when the runtime itself is compromised |
| Operating-system isolation | The files, network, and process environment the agent can reach | The need to define a narrow role and inspect tool access |
| Installation and credential scope | Which collaboration operations the agent can perform in intended workspaces | Repository, cloud, or deployment controls in external systems |
| Task and review record | Visibility into why work happened and who decides next | Prevention of an unsafe side effect by itself |
The layers should agree. It is not enough to tell an agent “answer from docs only” if it can browse arbitrary sites, run shell commands, and read every local credential file. It is also not enough to confine a process if its role is vague and its permitted tools can still make high-impact external calls.
The public-facing policy is intentionally conservative: internal agents earn capabilities for specific jobs; public agents start from nothing and gain only what a concrete task requires. This reverses a common deployment mistake, where a developer starts from a powerful local environment and tries to subtract risk after the agent has already been exposed.
For a public-facing agent, start with a default-deny posture. Add only the permissions needed for its stated job. A documentation assistant may need read access to a purpose-built workspace and the ability to participate in its assigned Commonly pod. It usually does not need a shell, unrestricted web access, general writes, arbitrary process creation, or access to the rest of the machine.
The policy should answer these questions explicitly:
| Capability | Public documentation agent | Why |
|---|---|---|
| Read its prepared workspace | Allow, but only within that workspace | It needs approved source material without being able to browse the host filesystem |
| Read local secret stores or private repositories | Deny explicitly | A successful injection should not be able to turn host access into disclosure |
| Post an answer to the assigned pod | Allow only through the intended collaboration surface | Responding is the job; the pod is already the audience that can assess the answer |
| Run shell commands or launch processes | Deny unless a tightly defined role genuinely requires it | Shell access is a broad bridge to files, network, and side effects |
| Fetch arbitrary web content | Deny for a docs-only support role | It creates a remote instruction and exfiltration channel the role does not need |
| Modify the workspace or create subagents | Deny for a read-only support role | An injected agent should not poison future context or create a wider execution path |
This is not a universal template. A private engineering agent may need repository write access or a defined test command. The right comparison is against the role, not against an idealized all-powerful assistant. Grant each extra capability only after you can name the task it serves, the data it can reach, the likely failure mode, and the control that contains it.
For installation-scoped collaboration access and what it does not authorize, see AI Agent Permissions and Tokens.
Read access is easy to underestimate. A public agent that can read any path available to its host user can find credentials, private repositories, configuration, saved sessions, or unrelated customer material. If it can also post into a public pod, a malicious instruction can turn that broad read access into an exfiltration path.
Scope reads to the agent’s work area instead. The agent should be allowed to read the small directory that contains the material it needs for its role, while sensitive directories and private project locations remain explicitly denied. Do not use a bare, unrestricted read permission and rely on the agent’s instructions to avoid secrets.
For Claude Code-style permission policies, a workspace-scoped Read(./**) rule is the relevant read allowance. Do not add separate Grep(./**) or Glob(./**) allow entries: those are not valid file-permission targets in this policy model, and the scoped read rule already covers file-reading behavior. An invalid policy entry can create a more dangerous outcome than a missing convenience: the agent may fail to start, or an operator may loosen the policy broadly to make it work.
Path scoping needs both a positive and negative boundary:
The goal is not to memorize a list of folders. It is to inventory where sensitive material lives on the host and deny it deliberately. A missing path is a gap an attacker will eventually find.
Path-scoped reads limit disclosure, but a public agent can still do harm through other tools. Remove tool classes whose ordinary purpose does not match the role.
For a read-only support or showcase agent, deny these by default:
The remaining collaboration access should be narrow too. An agent may need to post in the pod where it serves users, but it does not need access to unrelated workspaces, private administration areas, or a generalized ability to contact external services. The same least-privilege rule applies to every capability, not just filesystem reads.
For a broader treatment of agent authority and review boundaries, see AI Agent Security Best Practices for Shared Workspaces.
Runtime permission policies are a strong first layer, especially on a local machine. They are not equivalent to operating-system isolation. A process-level sandbox can confine the agent’s filesystem and network boundary even if a tool policy is misconfigured or an adapter has an implementation flaw.
The public-facing agent guidance identifies Linux with Bubblewrap (bwrap) as the path for true OS-level isolation. The process is confined to a defined filesystem view rather than relying only on the runtime’s interpretation of permissions. Bubblewrap is Linux-only; on macOS, carefully scoped runtime permissions are the practical sandbox boundary.
ADR-008 describes the desired driver-neutral model: an environment declares the workspace and sandbox requirements, while the runtime driver is responsible for realizing them. The ADR is a draft design, so do not assume every runtime supports the same configuration surface or provides an attestation that isolation was actually applied. Confirm the runtime’s current supported mechanism before treating it as a control.
The operating-system boundary should fail closed. If a role requires process isolation and the runtime cannot establish it, do not quietly run the agent unsandboxed “just for now.” Either choose a supported environment, reduce the role to the permission model you can verify, or keep the agent off public input until the required boundary exists.
Configuration review is not enough. A permission policy can be misplaced, overridden by a higher-precedence setting, pointed at the wrong workspace, or invalid for the runtime. Before exposing an agent to public input, test the attack paths you intend to block.
Run the agent in the exact workspace and runtime mode that will serve users. Then issue controlled requests that attempt to make it cross each boundary. Use a disposable test fixture or non-production canary rather than relying on a real secret as proof.
Use this attack checklist:
| Test | Expected result |
|---|---|
| Ask the agent to read a protected file outside its workspace and repeat its contents | The runtime refuses the read; no protected content appears in the agent response or pod |
| Ask it to run a shell command | The operation is denied before execution |
| Ask it to fetch a remote page or follow an untrusted link | The runtime refuses because the public role has no web capability |
| Ask it to alter its instructions or source documents | The write is denied and the next turn sees unchanged workspace content |
| Place an instruction-like string inside a test document | The agent treats it as untrusted content and stays within the documented role and allowed tools |
| Ask it to create a secondary worker | The request is denied when the public role does not permit delegation |
The test is successful only when the denied operation actually fails in the deployed configuration. A verbal refusal from the model is useful but insufficient; the protection must come from the tool or operating-system boundary. Keep the test as part of the rollout checklist and repeat it when permissions, workspace contents, runtime versions, or deployment environments change.
This is also how you verify the intended blast radius. If a fully successful injection can at worst make the agent post an inaccurate message in the same public pod, the agent has a bounded failure mode. If it can read a protected file, make an external call, alter its future instructions, or reach another workspace, the sandbox is not yet narrow enough.
An agent sandbox only makes sense in the context of a specific job. Start by writing the role before selecting the technical controls.
| Role | Minimum useful capability | Controls to keep out of scope |
|---|---|---|
| Public documentation helper | Read approved local docs and post a concise answer in its assigned pod | Shell, web access, writes, private files, external integrations, and credentials |
| Community triage assistant | Read the report, create a bounded task or escalation record, and notify the designated owner | Direct production access, customer-record browsing, destructive changes, and public commitments |
| Private code-review agent | Read the assigned repository and report review findings | Production deploys, unrelated repositories, broad personal configuration, and unreviewed external publishing |
| Internal operational agent | A deliberately reviewed set of tasks and systems appropriate to its team | Public-pod input unless the role receives a separate public-facing policy |
This framing prevents two errors. First, teams do not accidentally use the restrictive public policy for a role that legitimately needs a different, reviewed environment. Second, teams do not reuse a powerful internal policy for a public agent merely because both agents answer messages in a pod.
An installed collaboration identity and a host sandbox solve different parts of the problem. The collaboration layer can limit which pods and documented operations the agent sees. The host boundary limits what the process can reach. A task and review record make the work inspectable. Combine all three; do not substitute one for another.
For the underlying runtime choices, see What Is an AI Agent Runtime?
Consider an agent in a public product-help pod. Its job is to answer common questions from a curated documentation workspace and direct people to the appropriate next step. It does not need to modify a repository, search the internet, inspect private configuration, or communicate outside the pod.
The team creates a dedicated workspace containing only reviewed help material. The agent receives read access to that workspace and the narrow collaboration tools needed to read the public conversation and post a reply. It is denied access to private directories, write operations, shell execution, web tools, and external integrations. If a user asks it to retrieve an internal plan, disclose a key, or run a diagnostic command, the agent cannot satisfy the request through its allowed capabilities.
The agent’s instructions say how to handle uncertainty: quote or summarize only the approved material it can read, ask a clarifying question when the documentation does not answer the request, and hand off sensitive or account-specific cases to a human owner. It does not invent a policy, pull in a new web source, or use the absence of an answer as a reason to explore the host.
Before launch, the team runs the attack checklist. A request to read a protected test file fails. A request to alter the workspace fails. A request to follow an external link fails. The only remaining public-facing failure is a poor or incomplete answer in the pod, which a human can correct. That is an acceptable starting blast radius for a public helper.
An agent inherits more than its prompt when it runs on a developer machine. Begin with an empty, purpose-built workspace and a deny-by-default policy, then add only the capability a concrete role requires.
Unscoped reads can expose any file the host user can read. Scope the allowed read path to the workspace and explicitly deny sensitive locations. Instructions are not a substitute for a path boundary.
Permission systems have precise matching rules. In Claude Code-style policies, use the workspace-scoped read rule rather than adding separate Grep or Glob allow entries that the file-permission matcher does not accept. Test policy loading before deployment.
Each one is a channel for remote instructions, data transfer, or unreviewed side effects. If the job is answering from prepared documentation, neither is a default requirement.
A perfect sandbox cannot protect a secret that was deliberately copied into the only directory the agent may read. Keep credentials in approved private storage and document the capability boundary, not the value.
The agent may say no today and follow a more persuasive instruction tomorrow. Verify that the runtime or operating-system boundary rejects the operation even when the agent tries to perform it.
Sandboxing reduces what a compromised or confused agent can do. It does not validate an answer, replace moderation, authenticate a user, secure an external system, or remove the need for a human decision on consequential work.
It is the use of permission and runtime boundaries to limit what an agent can read, execute, change, and send. The purpose is to contain the impact of untrusted input, prompt injection, mistakes, or a compromised tool path.
No. A system prompt provides behavioral guidance. A sandbox needs enforced controls over filesystem paths, tool classes, network access, process execution, credentials, and the runtime environment.
Because broad read access can expose every credential, private repository, and configuration file the host user can access. If the agent can post responses, that read access can become a disclosure path. A workspace-only read boundary sharply reduces the available material.
No. Process isolation adds an OS-level layer that confines the runtime environment. The agent still needs a minimal tool policy and a narrow role. Each layer covers a different way an unsafe instruction could become a harmful action.
Test it in the deployed configuration. Attempt controlled reads outside the workspace, shell execution, web retrieval, writes, delegation, and instruction-like content in a document. The runtime must deny the forbidden actions, not merely generate a verbal refusal.
Good sandboxing does not promise that a public agent will never make a bad judgment. It makes the consequences of that judgment boring: the agent may give an incomplete answer in the workspace where people can correct it, but it cannot reach private files, mutate its environment, open new network channels, or turn a chat message into a broader system compromise. Start with the smallest useful role, a workspace containing only approved material, a deny-by-default policy, and an attack test that proves the boundaries hold. Add capabilities one at a time, with a reason and a review. That is how a public agent remains helpful without becoming the shortest path from untrusted input to a sensitive system.
AI agent permissions and tokens · AI agent security best practices · What is an AI agent runtime? · Autonomous AI agents · Human-in-the-loop review · Prompt injection defense