Claude Code sandbox

Claude Code can edit files, run shell commands, install packages, and call MCP tools. That is what makes it useful. It also means a bad command runs with your user account’s permissions unless something outside the model stops it.

A Claude Code sandbox gives the agent room to work without handing it the rest of your machine. The important part is where that boundary lives. A prompt can ask the model to stay inside the project. A kernel sandbox can make leaving the project fail.

This guide sets up both the friendly policy layer and the harder OS boundary.

Quick setup

Install agentjail:

curl -fsSL https://agentjail.io/install.sh | sh

The installer registers agentjail as a Claude Code PreToolUse hook. That hook checks each tool call before Claude Code runs it.

Launch Claude Code through the sandbox:

agentjail run -- claude

That command starts Claude Code with two layers active:

1. The hook evaluates the requested tool call against local Rego policy.
2. The OS sandbox limits what Claude Code and its child processes can reach.

You can keep using Claude Code normally. The difference appears when it reaches for a sensitive file, destructive command, blocked MCP server, or disallowed network destination.

What the sandbox actually does

On macOS, agentjail uses Apple Seatbelt. On Linux, it uses Landlock. Both are part of the operating system, so the restriction is inherited by subprocesses.

That inheritance matters. A shell rule might recognize a direct command such as cat ~/.ssh/id_rsa. It is much harder for a shell rule to understand every possible Python script, eval, encoded pipeline, or helper process. The kernel sees the resulting file access either way.

By default, agentjail protects credential and configuration locations such as:

• ~/.ssh
• ~/.aws
• ~/.gnupg
• ~/.docker
• ~/.kube
• private keys and .env files
• agentjail’s own policy directory

The complete platform behavior is documented in the OS-native sandbox reference.

Hook policy and sandboxing solve different problems

You want both layers because they answer different questions.

Question	Tool-call policy	OS sandbox
Is this MCP server allowed?	Yes	No
Should a force-push require approval?	Yes	No
Why was this action blocked?	Gives a readable reason	Usually returns EPERM
Can a Python subprocess read an SSH key?	Not reliably	Yes, it can block the read
Can a shell trick bypass command matching?	Sometimes	The resulting access is still restricted

The hook gives you useful decisions: allow, ask, or deny. The sandbox is the backstop when the command that eventually runs does not resemble the original tool call.

Restrict Claude Code’s network access

Filesystem isolation does not automatically make network access safe. A coding agent still needs package registries, source hosts, and its model provider, but it probably does not need every host on the internet.

Add the hosts your work requires to ~/.agentjail/policy.yaml:

network:
  allowed_hosts:
    - api.github.com
    - registry.npmjs.org
    - "*.example.com"

Request the transparent tunnel when you want hostname-based egress checks and traffic capture:

agentjail run --tunnel -- claude

Agentjail does not currently provide a --require-tunnel flag. On Linux, tunnel setup can fall back to netproxy when the transparent path is unavailable, and some network features depend on kernel and platform support. Check the launch output and agentjail doctor before relying on the network layer in CI or a security test.

Check MCP access too

Claude Code can connect to MCP servers that reach well beyond the current repository. Treat those servers like dependencies with permissions, not like harmless editor extensions.

Start with an inventory:

agentjail mcp scan

Then allow the servers you trust and block individual tools that are too broad:

agentjail mcp allow github
agentjail mcp tool block github delete_repo
agentjail mcp tool ask github create_repo

The MCP security guide walks through the threat model and a practical review checklist.

Verify the boundary yourself

Do not stop at “installed successfully.” Test an action that should fail.

First, confirm the hook decision:

echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"rm -rf ~/.ssh"}}' \
  | agentjail-hook

Then test the OS boundary with a harmless read attempt:

agentjail-shield -- sh -c "cat ~/.ssh/id_rsa"

The second command should fail with an operation-not-permitted error even though it does not pass through Claude Code’s tool hook.

Run the built-in diagnostic when the result is not what you expect:

agentjail doctor

It shows which sandbox and network controls are active and where each setting came from.

A sensible Claude Code security baseline

For day-to-day work:

1. Keep the PreToolUse hook installed.
2. Launch with agentjail run -- claude, not a bare claude command.
3. Keep credentials outside the repository whenever possible.
4. Allowlist MCP servers and review sensitive tools one by one.
5. Restrict outbound hosts for unattended or production-adjacent work.
6. Test the policy before disabling Claude Code’s own permission prompts.
7. Review denials and approvals instead of treating the log as decoration.

On unsupported operating systems, including Windows without a Linux layer, the OS sandbox currently fails open with a warning. The hook policy still runs, but that is not the same boundary. If the kernel layer is required, run Claude Code on a supported macOS or Linux environment.

Next steps

• Claude Code integration: hook installation and the exact settings entry.
• Safely skipping permission prompts: what to check before removing manual approvals.
• AI agent security guide: a wider threat model covering credentials, tools, network access, and auditability.