dev-bubble 0.2.0__tar.gz

dev_bubble-0.2.0/.claude/CLAUDE.md

@@ -0,0 +1,166 @@
+# bubble Architecture Guide
+
+This file helps Claude Code sessions understand the bubble codebase.
+
+## What This Project Is
+
+`bubble` provides containerized development environments via Incus containers. The primary interface is URL-based: `bubble <github-url>` creates (or re-attaches to) an isolated container with VSCode Remote SSH. Language-specific hooks (currently Lean 4) auto-detect the project type and select the right image.
+
+## Package Structure
+
+```
+bubble/
+├── cli.py              # Click CLI with BubbleGroup (routes unknown args to `open` command)
+├── config.py           # TOML config at ~/.bubble/config.toml
+├── target.py           # Target parsing: GitHub URLs, local paths, bare PR numbers
+├── repo_registry.py    # Learned short name → owner/repo mappings (~/.bubble/repos.json)
+├── naming.py           # Container name generation: <repo>-<source>-<id>
+├── git_store.py        # Shared bare repo management at ~/.bubble/git/
+├── clean.py            # Container cleanness checking (safe to discard?)
+├── lifecycle.py        # Registry tracking for active bubbles
+├── network.py          # Network allowlisting via iptables inside containers
+├── vscode.py           # SSH config generation + `code --remote` launching
+├── automation.py       # Periodic jobs: launchd (macOS), systemd (Linux)
+├── relay.py            # Bubble-in-bubble relay daemon (Unix socket, validation, rate limiting)
+├── hooks/
+│   ├── __init__.py     # Hook ABC, discover_hooks(), select_hook()
+│   └── lean.py         # LeanHook: detects lean-toolchain, uses lean image
+├── runtime/
+│   ├── base.py         # Abstract ContainerRuntime interface
+│   ├── incus.py        # IncusRuntime: shells out to `incus` CLI
+│   └── colima.py       # macOS: ensure Colima VM is running with correct resources
+├── images/
+│   ├── builder.py      # Image build via IMAGES registry dict (recursive parent building)
+│   └── scripts/
+│       ├── base.sh     # Ubuntu 24.04 + git + ssh + build-essential (user: "user")
+│       ├── lean.sh     # elan + VS Code Lean extension (derives from base, no toolchains)
+│       └── lean-toolchain.sh  # Installs one specific Lean toolchain (for versioned images)
+```
+
+## Key Design Decisions
+
+### URL-First Interface
+The primary command is `bubble <target>`. A custom `BubbleGroup(click.Group)` routes any unknown first argument to the implicit `open` command. Targets are parsed by `target.py` into a `Target(owner, repo, kind, ref, local_path)` dataclass. Supported target forms:
+- GitHub URLs: `https://github.com/owner/repo/pull/123`
+- Shorthand: `owner/repo`, `mathlib4/pull/123`, `mathlib4`
+- Local paths: `.`, `./path`, `/absolute/path` (extracts owner/repo from git remote)
+- Bare PR numbers: `123` (uses current directory's repo)
+- `--path` flag for disambiguation: `bubble --path mydir`
+
+Short names are resolved via `RepoRegistry`, which learns mappings automatically on first use. Local paths use the local `.git` as the `--reference` source for fast cloning, and support unpushed branches by fetching refs from the mounted local repo.
+
+### Language Hooks
+The `hooks/` package provides a pluggable system for language-specific behavior. Each `Hook` subclass implements `detect()` (check bare repo for language markers), `image_name()`, `post_clone()`, `vscode_extensions()`, and `network_domains()`. Hook detection runs against the host bare repo via `git show <ref>:<file>` — no container needed.
+
+### Runtime Abstraction
+`ContainerRuntime` (base.py) is an abstract interface. `IncusRuntime` is the only implementation today. Docker/Podman support is a stretch goal — the abstraction exists to make that possible without refactoring.
+
+### Git Object Sharing
+The core performance optimization. Host maintains bare mirror repos (`git clone --bare`). Containers clone with `git clone --reference /shared/git/repo.git url` — git alternates share immutable objects. Each container has fully independent refs/branches/working tree. `update_all_repos()` discovers repos from the `~/.bubble/git/*.git` directory listing.
+
+### Image Registry
+Images are defined in `builder.py`'s `IMAGES` dict with script and parent references. Building is recursive — if a parent image is missing, it's built first. Static images: `base` (from Ubuntu 24.04) and `lean` (from base, elan + VS Code extension only, no toolchains).
+
+### Lazy Lean Toolchain Images
+The `lean` image has only elan (no toolchains pre-installed). When `LeanHook` detects a project, it reads `lean-toolchain` and parses the version. For stable/RC versions (v4.X.Y, v4.X.Y-rcK), it requests image `lean-v4.X.Y`. If that image exists, it's used directly. If not, the plain `lean` image is used (elan downloads the toolchain on demand) and a background build of the versioned image is triggered for next time. Dynamic images are built via `build_lean_toolchain_image()` in `builder.py`. Nightlies and custom toolchains always use the plain `lean` image.
+
+### Colima on macOS
+Incus requires Linux. On macOS, Colima runs a lightweight Linux VM with Apple's Virtualization.Framework (`--vm-type vz`). The `ensure_colima()` function starts it if needed.
+
+### SSH via ProxyCommand
+Each container runs sshd. Rather than port forwarding (which doesn't work well through Colima on macOS), we use `ProxyCommand incus exec <name> -- su - user -c "nc localhost 22"`. SSH config entries are auto-generated in `~/.ssh/config.d/bubble`.
+
+### Container Naming
+Names are `<repo>-<source>-<id>` (e.g., `mathlib4-pr-12345`). Numeric suffix for collisions. The `open` command checks for existing containers by generated name and registry lookup before creating new ones.
+
+### Container Lifecycle
+```
+created → running ⇄ paused → destroyed
+```
+
+### Network Allowlisting
+Uses iptables rules inside containers (not Incus ACLs) for portability across Colima/native setups. IPv6 is blocked entirely. DNS restricted to container resolver only. No outbound SSH. Base allowlist comes from config.toml; hooks contribute additional domains (e.g., Lean adds `releases.lean-lang.org`).
+
+### Security Model
+The `user` account has no sudo and a locked password. Network allowlisting is applied on container creation. SSH keys are injected via `incus file push` (not shell interpolation). All user-supplied values in shell commands are quoted with `shlex.quote()`. Each container mounts only its specific bare repo, not the entire git store.
+
+## How to Add a New Language Hook
+
+1. Create `bubble/hooks/<language>.py` with a class extending `Hook`
+2. Implement `detect()` to check for language markers in the bare repo
+3. Implement `image_name()` to return the image to use
+4. Add image script in `images/scripts/<name>.sh` and entry in `builder.py`'s `IMAGES` dict
+5. Register the hook in `hooks/__init__.py`'s `discover_hooks()`
+
+## How to Add a New Command
+
+1. Add a `@main.command()` function in `cli.py`
+2. Load config with `load_config()`, get runtime with `get_runtime(config)`
+3. Use `runtime.exec()`, `runtime.launch()`, etc. for container operations
+
+## Data Locations
+
+- `~/.bubble/config.toml` — user settings
+- `~/.bubble/git/` — bare repo mirrors
+- `~/.bubble/repos.json` — learned repo short name mappings
+- `~/.bubble/registry.json` — bubble state tracking
+- `~/.bubble/relay.sock` — relay daemon Unix socket (when enabled)
+- `~/.bubble/relay-tokens.json` — relay auth tokens per container
+- `~/.bubble/relay.log` — relay request log
+- `~/.bubble/vscode-commit` — VS Code commit hash baked into current base image
+- `~/.ssh/config.d/bubble` — auto-managed SSH config
+
+## Automation
+
+Automation is installed automatically on first bubble creation. On macOS, launchd jobs:
+- `com.bubble.git-update` — hourly git store refresh
+- `com.bubble.image-refresh` — weekly base image rebuild
+- `com.bubble.relay-daemon` — persistent relay daemon (installed via `bubble relay enable`)
+
+On Linux, equivalent systemd user timers/services are installed.
+
+## Bubble-in-Bubble Relay
+
+The relay allows running `bubble` from inside a container. Architecture:
+
+```
+Container                              Host
+────────                              ────
+/usr/local/bin/bubble (stub)          bubble relay daemon
+  → /bubble/relay.sock (Incus proxy)  ← ~/.bubble/relay.sock
+  sends {"target": "..."}              validates, rate-limits, logs
+  reads {"status": "ok", ...}          calls bubble open
+```
+
+- Opt-in via `bubble relay enable` (installs daemon, sets config)
+- Security: known repos only (`~/.bubble/git/` must exist), no local paths, rate limited (3/min, 10/10min, 20/hr per container), all requests logged
+- Container identifies itself via `/bubble/container-id` file
+- Relay daemon runs as launchd (macOS) or systemd (Linux) service
+- Code: `bubble/relay.py` (daemon + validation), `bubble/images/scripts/base.sh` (stub + client)
+
+## Testing Bubbles
+
+**Never run `bubble` with `--no-interactive` on the user's behalf.** When the user wants to test bubble, tell them the command and let them run it themselves. The user wants to see the live output in their terminal and interact with the result (VS Code window, SSH session). Running it non-interactively from a tool call hides the output and wastes time.
+
+## VS Code Integration Notes
+
+### Workspace Trust
+The workspace trust dialog is a **local VS Code client** decision, not controlled by remote server settings. We pass `--disable-workspace-trust` when launching VS Code in `open_vscode()`. Writing to `.vscode-server/data/Machine/settings.json` or `User/settings.json` inside the container does NOT suppress the trust prompt.
+
+### Clearing Trust State for Testing
+VS Code stores trusted workspace URIs in a SQLite database. To clear bubble-related trust entries:
+```python
+import json, sqlite3
+db = "/Users/kim/Library/Application Support/Code/User/globalStorage/state.vscdb"
+conn = sqlite3.connect(db)
+cur = conn.cursor()
+cur.execute("SELECT value FROM ItemTable WHERE key = 'content.trust.model.key'")
+data = json.loads(cur.fetchone()[0])
+data["uriTrustInfo"] = [e for e in data["uriTrustInfo"] if "bubble-" not in e["uri"].get("authority", "")]
+cur.execute("UPDATE ItemTable SET value = ? WHERE key = 'content.trust.model.key'", [json.dumps(data)])
+conn.commit()
+```
+VS Code must be restarted after modifying this database.
+
+### Pre-baked VS Code Server
+The base image pre-installs the VS Code Server binary matching the host's `code --version` commit hash. On each `bubble open`, if the hash has changed (VS Code updated), a background `bubble images build base` is triggered. The current bubble proceeds immediately; the next one gets the pre-baked server.

dev_bubble-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check bubble/ tests/
+      - run: ruff format --check bubble/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -v -m "not integration"
+
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Incus
+        run: |
+          sudo mkdir -p /etc/apt/keyrings/
+          curl -fsSL https://pkgs.zabbly.com/key.asc | sudo tee /etc/apt/keyrings/zabbly.asc > /dev/null
+          sudo sh -c 'cat <<EOF > /etc/apt/sources.list.d/zabbly-incus-stable.sources
+          Enabled: yes
+          Types: deb
+          URIs: https://pkgs.zabbly.com/incus/stable
+          Suites: $(. /etc/os-release && echo ${VERSION_CODENAME})
+          Components: main
+          Architectures: $(dpkg --print-architecture)
+          Signed-By: /etc/apt/keyrings/zabbly.asc
+          EOF'
+          sudo apt-get update
+          sudo apt-get install -y incus
+
+      - name: Initialize Incus
+        run: |
+          sudo incus admin init --minimal
+          # Allow non-root access (CI-only, ephemeral VM)
+          sudo chmod 666 /var/lib/incus/unix.socket
+          # Ensure IP forwarding and NAT for container internet access
+          sudo sysctl -w net.ipv4.ip_forward=1
+          sudo iptables -t nat -A POSTROUTING -s 10.0.0.0/8 -o eth0 -j MASQUERADE
+          sudo iptables -A FORWARD -i incusbr0 -j ACCEPT
+          sudo iptables -A FORWARD -o incusbr0 -m state --state RELATED,ESTABLISHED -j ACCEPT
+
+      - name: Install bubble
+        run: pip install -e ".[dev]"
+
+      - name: Build base image
+        run: bubble images build base
+
+      - name: Run integration tests
+        run: pytest -v -m integration

dev_bubble-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.env
+uv.lock

dev_bubble-0.2.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Kim Morrison
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

dev_bubble-0.2.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: dev-bubble
+Version: 0.2.0
+Summary: Containerized development environments powered by Incus
+Author-email: Kim Morrison <kim@tqft.net>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/kim-em/bubble
+Project-URL: Repository, https://github.com/kim-em/bubble
+Project-URL: Issues, https://github.com/kim-em/bubble/issues
+Keywords: containers,development,incus,lean,vscode
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Requires-Dist: tomli-w>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# bubble
+
+Containerized development environments for the Lean language, powered by [Incus](https://linuxcontainers.org/incus/).
+
+## Quick Start
+
+```bash
+# Install (use pipx or uv to avoid PEP 668 issues with system Python)
+pipx install dev-bubble    # or: uv tool install dev-bubble
+# For development:         uv pip install -e '.[dev]'
+
+# Open a bubble for a GitHub PR — just paste the URL, and you get a containerized VSCode window!
+bubble https://github.com/leanprover-community/mathlib4/pull/35219
+
+# Shorter forms work too
+bubble leanprover-community/mathlib4/pull/35219
+bubble mathlib4/pull/35219    # after first use, short names are learned
+
+# Branch or commit
+bubble leanprover-community/mathlib4/tree/some-branch
+bubble leanprover-community/mathlib4/commit/abc123
+
+# Default branch
+bubble leanprover-community/mathlib4
+
+# From a local git repo — opens the current branch in a bubble
+bubble .
+bubble ./path/to/repo
+
+# PR number shorthand (when in a cloned repo)
+bubble 123                   # opens PR #123 for the current repo
+
+# List your bubbles
+bubble list
+
+# SSH instead of VSCode
+bubble https://github.com/leanprover/lean4 --ssh
+
+# Just create, don't open anything
+bubble leanprover/lean4 --no-interactive
+
+# Pause a bubble
+bubble pause mathlib4-pr-35219
+
+# Destroy permanently
+bubble destroy mathlib4-pr-35219
+```
+
+## How It Works
+
+Each "bubble" is a lightweight Linux container (via Incus) with:
+- Your project cloned and ready to work on
+- SSH server for VSCode Remote connection
+- Network restricted to allowed domains only
+- Language-specific tooling when detected (e.g. Lean 4 via elan)
+
+**URL-first interface**: The primary command is `bubble <target>`. Targets can be full GitHub URLs, partial URLs, org/repo paths, or learned short names. If a bubble already exists for that target, it re-attaches instead of creating a new one.
+
+**Shared git objects**: A bare mirror of each repo is maintained on the host. Containers clone via `git --reference`, sharing the immutable object store. This means creating a new bubble for a mathlib PR downloads only the few new commits, not the entire 1.5GB repo.
+
+**Language hooks**: bubble automatically detects the project's language and selects the right image. For Lean 4 projects (detected via `lean-toolchain`), the container includes elan, pre-installed VS Code extensions, and auto-downloads the mathlib cache when needed.
+
+**Network allowlisting**: Containers can only reach allowed domains (GitHub by default, plus language-specific domains like `releases.lean-lang.org` for Lean). IPv6 is blocked, DNS is restricted to the container resolver, and outbound SSH is blocked. Configurable in `~/.bubble/config.toml`.
+
+## Requirements
+
+- **macOS**: Homebrew, then `brew install colima incus`
+- **Linux**: Incus installed natively ([install guide](https://linuxcontainers.org/incus/docs/main/installing/))
+- **VSCode** with [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `bubble <target>` | Open (or create) a bubble for a GitHub URL/repo |
+| `bubble list` | List all bubbles |
+| `bubble pause <name>` | Freeze a bubble |
+| `bubble destroy <name>` | Delete a bubble permanently |
+| `bubble cleanup` | Destroy all clean bubbles (no unsaved work) |
+| `bubble images list\|build` | Manage base images |
+| `bubble git update` | Refresh shared git mirrors |
+| `bubble network apply\|remove <name>` | Manage network restrictions |
+| `bubble automation install\|remove\|status` | Manage periodic jobs |
+| `bubble relay enable\|disable\|status` | Manage bubble-in-bubble relay |
+| `bubble doctor` | Diagnose and fix common issues |
+
+## Images
+
+Images are built automatically on first use.
+
+| Image | Contents |
+|-------|----------|
+| `base` | Ubuntu 24.04, git, openssh-server, build-essential, pre-baked VS Code Server |
+| `lean` | base + elan, leantar, VS Code Lean 4 extension, auto-cache extension |
+| `lean-v4.X.Y` | lean + specific toolchain pre-installed (built lazily on demand) |
+
+`base` and `lean` are static images you can rebuild with `bubble images build <name>`. Versioned `lean-v4.X.Y` images are built automatically in the background when a project uses a stable/RC toolchain not yet cached — the current bubble proceeds immediately with elan downloading the toolchain on demand, and the next bubble for that version starts instantly.
+
+For mathlib or mathlib-dependent projects, a VS Code terminal automatically runs `lake exe cache get` when the workspace opens.
+
+## Configuration
+
+Config lives at `~/.bubble/config.toml`. Created automatically on first use.
+
+Set `BUBBLE_HOME` to override the data directory (default: `~/.bubble`):
+```bash
+export BUBBLE_HOME=/data/bubble
+```
+
+```toml
+[runtime]
+backend = "incus"
+colima_cpu = 24          # macOS: CPUs for the Colima VM
+colima_memory = 16       # macOS: GB of RAM
+colima_vm_type = "vz"    # macOS: Apple Virtualization.Framework
+
+[network]
+allowlist = [
+  "github.com",
+  "raw.githubusercontent.com",
+  "release-assets.githubusercontent.com",
+  "objects.githubusercontent.com",
+  "codeload.githubusercontent.com",
+]
+```
+
+## Bubble-in-Bubble
+
+You can run `bubble` from inside a container to open another bubble on the host. This is useful when reviewing a related PR while working on a feature branch.
+
+```bash
+# On the host: enable the relay (one-time setup)
+bubble relay enable
+
+# Inside a container: open another bubble
+bubble leanprover/lean4/pull/456
+bubble mathlib4
+```
+
+The relay only allows opening repos already cloned in `~/.bubble/git/` — it cannot trigger cloning of new repos. Local paths are rejected. Existing bubbles need to be recreated after enabling the relay to get the relay socket.
+
+## Security
+
+- **No sudo**: The `user` account has no sudo access and a locked password
+- **Network allowlisting**: iptables rules restrict outbound connections to allowed domains only
+- **IPv6 blocked**: All IPv6 traffic is dropped
+- **DNS restricted**: DNS queries only go to the container's configured resolver
+- **No outbound SSH**: Containers cannot SSH out (VSCode uses `incus exec` ProxyCommand)
+- **SSH key-only auth**: Password authentication is disabled
+- **Shell injection hardening**: All user-supplied values are quoted with `shlex.quote()`
+- **Per-repo git mount**: Each container only sees its own bare repo, not the entire git store
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).