Bubblewrapped AI Agents

Runs AI coding agents (Claude Code and opencode) inside a bubblewrap sandbox.

Each agent gets an isolated home directory and cannot access your real home directory (SSH keys, shell config, credentials, etc.). Your current project directory is mounted read-write, and network access is allowed.

How it works

The wrapper scripts in .local/bin/ use bwrap to create a sandbox where:

• The agent's home is an isolated directory (~/.claude-bwrap or ~/.opencode) — separate from your real $HOME
• Your current working directory is bind-mounted read-write at /work inside the sandbox
• ~/.nvm and ~/.local/share/pnpm are bind-mounted read-only so the agent can use the same Node.js runtime
• All other namespaces (user, IPC, UTS, PID, cgroup) are unshared; network is shared

Prerequisites

• Linux
• bubblewrap (bwrap)
• Node.js via nvm

Install bubblewrap:

# Debian/Ubuntu
sudo apt install bubblewrap

# Fedora
sudo dnf install bubblewrap

# Arch
sudo pacman -S bubblewrap

Installation

1. Copy the wrapper scripts to your home directory

cp -r .local ~/
chmod +x ~/.local/bin/claude ~/.local/bin/opencode

2. Ensure ~/.local/bin is in your PATH

Add to ~/.bashrc or ~/.zshrc if not already present:

export PATH="$HOME/.local/bin:$PATH"

Then reload your shell:

source ~/.bashrc   # or ~/.zshrc

3. Install Claude Code into the sandbox prefix

npm install -g @anthropic-ai/claude-code --prefix=~/.claude-bwrap

This installs the claude binary to ~/.claude-bwrap/bin/, which is the first entry on $PATH inside the sandbox.

4. Install opencode into the sandbox prefix (optional)

npm install -g opencode-ai --prefix=~/.opencode

Usage

Run claude or opencode from your project directory as you normally would:

cd ~/my-project
claude

The agent will have full read-write access to ~/my-project (mounted at /work inside the sandbox) but cannot access anything else in your real home directory.

What the sandbox can and cannot access

Resource	Access
Current project directory	Read-write
~/.nvm	Read-only
~/.local/share/pnpm	Read-only
Network	Full access
Rest of $HOME	No access
/usr, /bin, /lib	Read-only (system binaries)
/tmp	Writable tmpfs (ephemeral)