# Claude Code sandbox

> Set up Claude Code with tool policy and OS sandboxing, then test filesystem, network, and MCP restrictions.

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:

```sh
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:

```sh
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](/docs/concepts/sandbox).

## 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`:

```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:

```sh
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:

```sh
agentjail mcp scan
```

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

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

The [MCP security guide](/docs/guides/mcp-security) 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:

```sh
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:

```sh
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:

```sh
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](/docs/integrations/claude-code): hook installation
  and the exact settings entry.
- [Safely skipping permission prompts](/docs/guides/skip-permissions): what to
  check before removing manual approvals.
- [AI agent security guide](/docs/guides/ai-agent-security): a wider threat
  model covering credentials, tools, network access, and auditability.