opencode-bwrap

Run opencode inside a bubblewrap sandbox — keeping AI-driven file operations confined to your current working directory.

What it does

opencode-bwrap is a thin shell wrapper that launches opencode inside a bwrap (bubblewrap) sandbox. The sandbox:

• Gives opencode read-write access only to your current working directory
• Blocks access to the rest of $HOME (no ~/.ssh, ~/Documents, etc.)
• Keeps network access open (required for LLM API calls)
• Isolates PID, IPC, UTS, and mount namespaces
• Passes through your opencode config, cache, and state directories
• Passes through your ~/.gitconfig and gh CLI auth (read-only)
• Supports NVM-managed Node.js installations

Requirements

• Linux
• bwrap — install via your package manager:

  # Debian/Ubuntu
  sudo apt install bubblewrap
  
  # Arch
  sudo pacman -S bubblewrap
  
  # Fedora
  sudo dnf install bubblewrap

• opencode installed and on $PATH

Installation

1. Copy opencode-bwrap to somewhere on your $PATH, for example:

   cp opencode-bwrap ~/.local/bin/opencode-bwrap
   chmod +x ~/.local/bin/opencode-bwrap

2. Run it from your project directory:

   cd /path/to/your/project
   opencode-bwrap

   Pass any opencode flags normally:

   opencode-bwrap --model anthropic/claude-sonnet-4-5

What the sandbox blocks

Resource	Behavior
Files outside $PWD	Not visible (no bind)
~/.ssh	Not mounted
$HOME (other than config dirs)	Empty virtual dir
Physical block devices (/dev/sda, etc.)	Not present
Host processes (other PIDs)	Not visible — isolated PID namespace
Privilege escalation (sudo)	Blocked — no setuid in namespace

What is passed through (read-only unless noted)

Resource	Mount type
$PWD (current directory)	read-write
~/.config/opencode	read-write
~/.local/share/opencode	read-write
~/.cache/opencode	read-write
~/.local/state/opencode	read-write
~/.gitconfig	read-only
~/.config/gh	read-only
$NVM_DIR	read-only
/usr, /etc	read-only

Adding more workspaces

Edit the WORKSPACES array at the top of the script:

WORKSPACES=(
    "$(pwd)"
    "$HOME/projects/other-repo"
)

Security notes

bwrap uses Linux namespaces — the same kernel is shared with the host. This is stronger isolation than running opencode directly, and lighter than a full VM. For most personal development use cases this is a practical tradeoff.

Key limitations to be aware of:

• The host kernel is shared. A kernel-level exploit could escape the sandbox.
• --new-session is intentionally omitted to preserve job control (Ctrl-Z / fg). This slightly reduces TIOCSTI protection.
• Anything explicitly bind-mounted is accessible to the sandboxed process.

License

MIT