Sandbox#

The sandbox provides OS-level process isolation for tool execution during reviews. It restricts filesystem access, network connectivity, and process lifetime.

Overview#

When sandbox.enabled = true (the default), tool execution runs inside an isolated environment:

• On Linux: bubblewrap (bwrap) provides user-namespace isolation.

• On Windows: Win32 Job Objects restrict process creation and enforce termination-on-close.

• On other platforms: a fallback mode runs processes with a timeout but no OS-level isolation. A warning is logged.

If sandbox creation fails (e.g. bwrap is not installed), the review continues without sandboxing and a warning is logged.

Linux: bubblewrap (bwrap)#

Prerequisites#

Install bubblewrap:

# Debian/Ubuntu
sudo apt install bubblewrap

# Fedora
sudo dnf install bubblewrap

# Arch
sudo pacman -S bubblewrap

How It Works#

The sandbox creates a minimal filesystem view with these mounts:

Additional paths from allowed_read_paths are mounted read-only. Paths from allowed_write_paths are mounted read-write. Non-existent paths are silently skipped.

The process runs with:

• --die-with-parent – the sandboxed process is killed when the parent exits.

• --new-session – a new session ID prevents terminal control attacks.

• A clean environment: only HOME=/tmp and PATH=/usr/local/bin:/usr/bin:/bin are set, plus any variables defined in the MCP server config.

Network Policy#

For fine-grained network control with limited, combine with external firewall rules (e.g. iptables, nftables).

Windows: Job Objects#

How It Works#

On Windows, the sandbox creates a Win32 Job Object with these constraints:

• JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE – all processes in the job are terminated when the job handle is closed.

• JOB_OBJECT_LIMIT_ACTIVE_PROCESS – limits the job to 32 concurrent processes.

The process runs in the temporary working directory with environment variables from the MCP server config.

Limitations#

Windows Job Objects do not provide filesystem or network isolation. The process has the same filesystem and network access as the claude-review service. For stronger isolation on Windows, consider running claude-review inside a container.

Configuration#

[sandbox]
enabled = true                     # Enable sandbox (default: true)
allowed_read_paths = ["/data/models"]  # Extra read-only mounts (Linux only)
allowed_write_paths = ["/tmp/output"]  # Extra read-write mounts (Linux only)
network_policy = "none"            # "none", "limited", or "full" (default: "none")
timeout_seconds = 300              # Kill process after this many seconds (default: 300)

Fields#

Network Policies#

Disabling the Sandbox#

Set enabled = false to run all tool executions without OS-level isolation. The process still runs in a temporary directory and is subject to the timeout.

[sandbox]
enabled = false

This is appropriate for trusted environments where tool execution does not pose a risk, or when running inside an already-isolated container.