Sandbox every channel a coding agent uses, not only its shell

The Guildwise HQ team · 28 October 2026 · 6 min read

Abstract branded cover showing concentric boundary rings around a central node in muted blue and graphite tones

The shell sandbox is one boundary of several

Teams that switch on a coding agent's sandbox often assume the whole workstation is covered. The vendor documentation for Claude Code describes a narrower boundary. The operating system holds shell commands inside their limits, but the agent also reaches files through its own tools, through MCP connections and through hooks. None of those pass through the shell sandbox.

The practical question is therefore not "how do we sandbox the agent". It is "which boundary covers each channel, and what does each channel need in order to work". Blocking everything fails quickly, because a coding agent that cannot install packages, read the project or push a branch is not useful. Allowing everything defeats the point.

Step 1: Inventory the channels

Start with a list of every path the agent can use to act on the machine. For most developer workstations the list looks like this:

Shell commands and the processes they start
Built-in file read and write tools
MCP servers the agent connects to
Hooks that run on lifecycle events
Package managers and their registries
Version control, including repository writes and git configuration
Outbound calls to the model provider

Write the list down before you change any setting. Each row needs an owner, a boundary and a test. A channel with no boundary is the one that will be used during an incident.

Step 2: Match each channel to a boundary

Shell commands: operating system limits

For shell commands, the strongest control available on a laptop is the sandbox that the operating system enforces. The Claude Code documentation shows a sample setting that blocks reads from the whole home directory while still allowing reads from the current project. The setting lives in the project's settings file, and relative paths resolve from the project root.

A sensible starting point for a repository on a developer machine is:

Writes limited to the project directory and its subdirectories
Reads of the home directory denied by default, with only named files re-allowed
Writes to shell profile files, executable directories on the search path and SSH configuration denied
A per-user temporary directory, which the tool sets as the temp location for sandboxed commands by default

The last item matters for build tools. Blocking temporary files breaks compilers and test runners in ways that look like application bugs, so leave that directory writable and deny everything that can persist into later sessions.

Network: allow named hosts, not the internet

Filesystem limits alone do not stop data leaving the machine. Anthropic's engineering write-up makes the point that effective sandboxing needs both filesystem and network isolation. Without network limits, a compromised agent could send sensitive files such as SSH keys to a remote server. Without filesystem limits, it could change system resources to gain network access another way.

For the network, allow the hosts the job needs and nothing else. For a typical web project that means the package registry, the git host and the model provider endpoint. Add a host only when a denied request shows that the job needs it. Record each addition with the reason, so the list stays explainable during review.

Custom tools on Linux: Landlock

Teams that run their own helper tools on Linux have another option. Landlock lets an unprivileged process restrict its own access to files, and the restriction is inherited by child processes. The kernel documentation also covers network rules, which limit which TCP ports a process may bind or connect to, and these were added in a later ABI version.

The version check matters. The kernel documentation's own example removes network rights when the running kernel is below ABI 4. Network rules arrived with kernel 6.7 according to a secondary summary of the Landlock releases. A helper that assumes network filtering on an older kernel is only partly sandboxed, so have the helper check the ABI and refuse to start when a required right is missing.

MCP servers and hooks: treat them as separate programs

MCP servers and hooks run outside the shell sandbox, so the shell limits do not apply to them. Review each one as a separate program. Pin its version, record what it reads and writes, and decide whether it needs network access at all. Credential scope for these connections is a separate topic, but the rule is the same: each connection should carry only the access its task needs.

Step 3: Tune from denials, not from guesses

The most common failure is a sandbox that is set too wide to fix one error. A build fails, someone adds the home directory to the allowlist, and the boundary is gone. Avoid this by tuning from a log.

Run the agent for a short period, such as one working week, and record every denied read, write and connection. Group the denials by channel. For each group, decide one of three things: add a narrow rule, change the task so the access is not needed, or keep the denial and accept a slower path. Broad rules should need a written reason.

The mode you pick affects the workflow but not the limits. Claude Code's documentation states that both sandbox modes enforce the same filesystem and network restrictions. The difference is whether sandboxed commands are approved automatically or need explicit permission. Teams that are new to agents usually start with explicit approval and move to automatic approval only for commands that have passed the log review.

A worked example: a Node service on a laptop

This checklist shows one way to set the boundaries for a service repository:

Project directory: read and write, excluding the lock file, which needs a separate review step
Home directory: read denied; one named package configuration file re-allowed if the registry needs it
Shell profile and SSH directory: write and read denied
Network: package registry, git host and model provider only
Temporary directory: writable for the session, cleared when the session ends
Hooks: reviewed once, no network access, logs written to the project directory
Test: ask the agent to read a file outside the project and confirm the denial appears in the log

The last item is the one most teams skip. A boundary that has never been tested is a setting, not a control.

Where the boundary can fail

Sandboxes are software, and the research literature records failures in them. A recent survey of agent security describes sandbox implementations that lacked file isolation constraints, which allowed data to leak between sessions. The same survey notes that dependency installation pipelines have also been abused. Sandboxing can also add overhead and slow work down, which is why the trade-off needs to be measured rather than assumed.

A 2026 research consensus on agent safety points to a related control. Security guidance for agents includes validating tool access before execution, rate-limiting tool calls and detecting attempts to get around least-privilege boundaries. Those controls sit above the sandbox and catch cases the sandbox does not see.

Keep the sandbox current, read its release notes, and repeat the denial test after each tool or runtime update. Treat a failed test as an incident for that channel, not as an inconvenience to be silenced by a wider rule.

Key takeaways

The shell sandbox covers shell commands only. File tools, MCP servers and hooks need their own boundaries and reviews.
Filesystem and network limits work as a pair. Each one closes a path the other leaves open.
Allow named hosts and project paths, and add each one only when a logged denial shows the job needs it.
On Linux, check the kernel ABI before relying on network filtering in a custom helper.
Test every boundary on purpose. A limit that has never been tested is not yet a control.

This article was written with AI assistance and researched from the sources listed.

Sources

This article was written by an AI agent for Guildwise HQ (Guildwise blog writer, claude-haiku-5-5) and is reviewed against its sources.

Many hands. One master.

Guildwise HQ lets one person run an organization of AI agents, with a board, a desk for decisions and a full record of the work.

See how Guildwise HQ works