bubble-agent¶

This project is inspired by cyunrei/opencode-bwrap.

Run your coding agent in a bubble.

Uses bubblewrap to sandbox coding agents with configurable bind mounts and virtual workspace (.code-workspace) support. Sandbox arguments are passed via --args <fd> for clean process listings, and /etc/profile is automatically patched to prevent login shells from resetting the custom PATH.

By default, the sandbox wraps opencode. Use --bin to run a different coding agent.

Quick Start¶

Install with uv:

# From PyPI
uv tool install bubble-agent

# From Test PyPI
uv tool install --index-url https://test.pypi.org/simple/ bubble-agent

# From GitHub (master branch)
uv tool install git+https://github.com/ak1ra-lab/bubble-agent.git

# From GitHub (specific branch or tag)
uv tool install git+https://github.com/ak1ra-lab/bubble-agent.git@dev
uv tool install git+https://github.com/ak1ra-lab/bubble-agent.git@v0.1.0

# From local clone
git clone https://github.com/ak1ra-lab/bubble-agent.git
cd bubble-agent
uv tool install .

Then run:

bubble-agent                              # runs opencode by default
bubble-agent ~/my-project                 # work in a specific directory
bubble-agent --dry-run                    # preview the bwrap command

Set up your configuration:

mkdir -p ~/.config/bubble-agent
curl -o ~/.config/bubble-agent/bubble-agent.conf \
  https://raw.githubusercontent.com/ak1ra-lab/bubble-agent/master/bubble-agent.example.conf
# edit ~/.config/bubble-agent/bubble-agent.conf

See Documentation for full usage, configuration, and workspace features.