Sandboxed Claude Code

Run Claude Code (Anthropic's AI coding assistant) in a security sandbox to limit its access to your system. This repository provides three different sandboxing approaches for different platforms and security requirements.

Why Sandbox Claude Code?

Claude Code is an AI agent that can read files, write code, and execute commands. While it's designed to be helpful and safe, defense-in-depth security practices suggest limiting any automated tool's access to only what it needs. Sandboxing provides:

• Filesystem isolation - Claude can only access your current project, not your entire home directory
• Capability restriction - Dropped privileges prevent potential privilege escalation
• Blast radius reduction - If something goes wrong, damage is contained
• Audit clarity - Clear boundaries make it easier to understand what Claude can and cannot do

Quick Start

| Platform | Recommended Approach | Command | |----------|---------------------|---------| | Linux | Bubblewrap | ./bubblewrap_claude.sh | | Linux (alternative) | Firejail | ./firejail_claude.sh | | macOS | Apple Container | ./container_claude.sh |

Approaches Compared

┌─────────────────────────────────────────────────────────────────────────────┐
│                          ISOLATION STRENGTH                                 │
│                                                                             │
│  Weaker                                                                     │
│    │                                                                        │
│    │   ┌──────────────┐                                                     │
│    │   │   Firejail   │  Namespaces + Seccomp                               │
│    │   │              │  Easy to configure, good defaults                   │
│    │   └──────────────┘                                                     │
│    │                                                                        │
│    │   ┌──────────────┐                                                     │
│    │   │  Bubblewrap  │  Namespaces (manual config)                         │
│    │   │              │  Maximum control, minimal overhead                  │
│    │   └──────────────┘                                                     │
│    │                                                                        │
│    │   ┌───────────────┐                                                    │
│    │   │Apple Container│  Hypervisor (VM)                                   │
│    │   │               │  Strongest isolation, higher overhead              │
│    ▼   └───────────────┘                                                    │
│  Stronger                                                                   │
└─────────────────────────────────────────────────────────────────────────────┘

Comparison Matrix

| Feature | Bubblewrap | Firejail | Apple Container | |---------|------------|----------|-----------------| | Platform | Linux | Linux | macOS | | Isolation Type | Linux namespaces | Namespaces + seccomp | Lightweight VM | | Startup Overhead | ~5ms | ~10ms | ~500ms-2s | | Memory Overhead | Minimal | Minimal | 256MB+ | | Escape Difficulty | Medium | Medium | Hard | | Configuration | Manual | Profile-based | Containerfile | | Syscall Filtering | Manual | Built-in | N/A (different kernel) | | Learning Curve | Steep | Moderate | Moderate |

---

1. Bubblewrap (Linux)

Best for: Linux users who want minimal overhead and maximum control.

How It Works

Bubblewrap (bwrap) uses Linux namespaces to create an isolated environment:

┌─────────────────────────────────────────────────────────────────┐
│                         HOST SYSTEM                             │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    BWRAP SANDBOX                          │  │
│  │                                                           │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │  │
│  │  │ Mount NS    │  │   PID NS    │  │  User NS    │        │  │
│  │  │             │  │             │  │             │        │  │
│  │  │ /usr (RO)   │  │ Isolated    │  │ Mapped UID  │        │  │
│  │  │ /lib (RO)   │  │ process     │  │             │        │  │
│  │  │ $PWD (RW)   │  │ tree        │  │             │        │  │
│  │  │ ~/.claude(RW│  │             │  │             │        │  │
│  │  └─────────────┘  └─────────────┘  └─────────────┘        │  │
│  │                                                           │  │
│  │                    ┌─────────────┐                        │  │
│  │                    │   Claude    │                        │  │
│  │                    │    Code     │                        │  │
│  │                    └─────────────┘                        │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Namespace isolation:

• Mount namespace - Custom filesystem view with selective bind mounts
• PID namespace - Isolated process tree (can't see/signal host processes)
• Network - Shared (required for Claude API)

Installation

# Debian/Ubuntu
sudo apt install bubblewrap

# Fedora/RHEL
sudo dnf install bubblewrap

# Arch Linux
sudo pacman -S bubblewrap

Usage

# Navigate to your project
cd /path/to/your/project

# Run Claude in sandbox
./bubblewrap_claude.sh

# Pass arguments to Claude
./bubblewrap_claude.sh -p "explain this codebase"

Filesystem Access

| Path | Access | Purpose | |------|--------|---------| | /usr, /lib, /bin | Read-only | System binaries and libraries | | /etc/resolv.conf, /etc/hosts | Read-only | Network configuration | | /etc/ssl | Read-only | TLS certificates | | $HOME/.gitconfig | Read-only | Git identity | | $HOME/.ssh/known_hosts | Read-only | SSH host verification | | $SSH_AUTH_SOCK | Read-write | SSH agent (git auth) | | $HOME/.nvm, $HOME/.local | Read-only | Node.js runtime | | $HOME/.npm | Read-write | NPM package cache | | $HOME/.claude | Read-write | Claude configuration | | $PWD | Read-write | Your project | | /tmp | tmpfs | Ephemeral scratch space |

Security Features

--unshare-pid           # Isolate process namespace
--die-with-parent       # Kill sandbox if parent dies
--ro-bind               # Read-only mounts for system paths
--tmpfs /tmp            # Fresh /tmp on each run

---

2. Firejail (Linux)

Best for: Linux users who want easier configuration with good security defaults.

How It Works

Firejail wraps bubblewrap-style namespaces with additional security layers:

┌─────────────────────────────────────────────────────────────────┐
│                         HOST SYSTEM                             │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                   FIREJAIL SANDBOX                        │  │
│  │                                                           │  │
│  │  ┌─────────────────────────────────────────────────────┐  │  │
│  │  │              SECCOMP FILTER                         │  │  │
│  │  │  Blocks dangerous syscalls: ptrace, mount, etc.     │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  │                          │                                │  │
│  │  ┌─────────────────────────────────────────────────────┐  │  │
│  │  │           CAPABILITY RESTRICTIONS                   │  │  │
│  │  │  caps.drop=all, nonewprivs, noroot                  │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  │                          │                                │  │
│  │  ┌─────────────────────────────────────────────────────┐  │  │
│  │  │              NAMESPACE ISOLATION                    │  │  │
│  │  │  Mount, PID, IPC namespaces                         │  │  │
│  │  └─────────────────────────────────────────────────────┘  │  │
│  │                          │                                │  │
│  │                    ┌─────────────┐                        │  │
│  │                    │   Claude    │                        │  │
│  │                    │    Code     │                        │  │
│  │                    └─────────────┘                        │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Additional protections over raw bubblewrap:

• Seccomp BPF - Syscall filtering blocks dangerous operations
• Capability dropping - All Linux capabilities removed
• No-new-privileges - Prevents privilege escalation via setuid binaries

Installation

# Debian/Ubuntu
sudo apt install firejail

# Fedora/RHEL
sudo dnf install firejail

# Arch Linux
sudo pacman -S firejail

Usage

Option A: Use the wrapper script

./firejail_claude.sh

Option B: Install the profile globally

# Copy profile to firejail config
cp claude.firejail.profile ~/.config/firejail/claude.profile

# Run with profile
firejail --profile=claude claude

Security Features

--caps.drop=all         # Drop ALL Linux capabilities
--nonewprivs            # No privilege escalation via execve
--noroot                # Disable root inside sandbox
--seccomp               # Enable syscall filtering
--private-tmp           # Isolated /tmp
--private-dev           # Minimal /dev
--nodvd --nosound       # Disable hardware access
--no3d --notv --novideo # Disable GPU/media devices

Profile Customization

Edit claude.firejail.profile to customize. Common modifications:

# Disable network (for offline analysis)
net none

# Add additional read-only paths
read-only ${HOME}/reference-docs

# Allow specific additional writable paths
whitelist ${HOME}/scratch-area