https://github.com/ak1ra-lab/bubble-agent

Run your coding agent in a bubble.
https://github.com/ak1ra-lab/bubble-agent

agent agentic bubblewrap bwrap claude-code codex opencode sandbox

Last synced: 1 day ago
JSON representation

Run your coding agent in a bubble.

• Host: GitHub
• URL: https://github.com/ak1ra-lab/bubble-agent
• Owner: ak1ra-lab
• License: mit
• Created: 2026-06-24T01:07:05.000Z (16 days ago)
• Default Branch: master
• Last Pushed: 2026-07-08T07:40:46.000Z (1 day ago)
• Last Synced: 2026-07-08T09:15:07.152Z (1 day ago)
• Topics: agent, agentic, bubblewrap, bwrap, claude-code, codex, opencode, sandbox
• Language: Python
• Homepage: https://ak1ra-lab.github.io/bubble-agent/
• Size: 109 KB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          
# bubble-agent

[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ak1ra-lab/bubble-agent/.github%2Fworkflows%2Fpublish-to-pypi.yaml)](https://github.com/ak1ra-lab/bubble-agent/actions/workflows/publish-to-pypi.yaml)

[![PyPI - Version](https://img.shields.io/pypi/v/bubble-agent)](https://pypi.org/project/bubble-agent/)

[![PyPI - Version](https://img.shields.io/pypi/v/bubble-agent?label=test-pypi&pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://test.pypi.org/project/bubble-agent/)

[![Docs](https://img.shields.io/badge/docs-online-0a7ea4)](https://ak1ra-lab.github.io/bubble-agent/)

> This project is inspired by [cyunrei/opencode-bwrap](https://github.com/cyunrei/opencode-bwrap).

Run your coding agent in a bubble.

Uses [bubblewrap](https://github.com/containers/bubblewrap) to sandbox coding agents with configurable bind mounts and virtual workspace (`.code-workspace`) support.  Sandbox arguments are passed via ``--args `` 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](https://github.com/anomalyco/opencode). Use `--bin` to run a different coding agent.

## Quick Start

Install with [uv]:

```shell

# 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:

```shell

bubble-agent                              # runs opencode by default

bubble-agent ~/my-project                 # work in a specific directory

bubble-agent --dry-run                    # preview the bwrap command

```

A default [configuration](https://ak1ra-lab.github.io/bubble-agent/configuration/) is

auto-created at `~/.config/bubble-agent/bubble-agent.conf` on first run — just run

`bubble-agent` and then edit the file to customize.

See [Documentation](https://ak1ra-lab.github.io/bubble-agent/) for full usage, configuration, and workspace features.

[uv]: https://docs.astral.sh/uv/