jailbee

JailBee runs isolated, per-branch development environments in
Incus system containers. Spin up multiple
full stacks in parallel on one host — each with its own services, Docker daemon,
IDE, and browser — without port conflicts, Docker name clashes, or
shared-database collisions.

The CLI is jailbee, or jb for short.

JailBee is project-agnostic: every repo supplies its own .jailbee/config.yaml. The
golden image ships stack-neutral by default — language toolchains (JDK, Node,
Python venv/pip, Docker) are bundled but opt-in, enabled per repo via
golden.stacks / golden.enable_snippets. It was built at GISGRO, which is
its origin, not its scope.

Key features

• Per-branch isolation — one full-stack container per git branch, running
  in parallel without port or Docker-name collisions.
• Host↔container git bridge — the container acts as a git remote; move
  commits with jailbee git push/pull/checkout instead of round-tripping
  through GitHub.
• Submodules that travel — sub-repos are initialised offline on
  jailbee new and their objects move with the superproject on every
  push/pull, so a repo with submodules needs no manual setup on either side.
• Nested Docker — security.nesting=true out of the box on Ubuntu 26.04.
• GUI passthrough — launch a JetBrains IDE (jailbee ide) and Chrome
  (jailbee chrome) from inside a container onto your Wayland session.
• Host sockets, shared — Wayland, PulseAudio, D-Bus and the gpg-agent are
  attached to every container, so git commit -S and ssh work inside while
  the private key never leaves the host (a smartcard still asks for its
  touch). Mount any other host socket the same way — an adb server, a
  database — and use it from inside.
• Network modes — per-container egress allowlist with strict and
  loose policies (jailbee net), safe for unattended agent runs. Entries are
  hostnames and ports (api.example.com:443), not IP addresses: JailBee
  resolves them into the kernel ACL, keeps a cumulative pool as CDN
  addresses rotate, and pins the container's /etc/hosts to match. Any
  protocol, not just HTTP — ssh, git+ssh and a database client work
  under the same list.
• First-class Claude Code — opt in with claude.enabled: true and every
  container gets Claude Code installed, sharing one login and one settings
  directory across the repo's containers while your host ~/.claude is
  never read. The Anthropic hosts are added to the strict-mode allowlist
  automatically, JailBee's own skills teach the in-container Claude to drive
  jailbee, and jailbee pr writes the PR title and body. Start it
  automatically in a tmux window and the container is ready for an
  unattended run the moment it boots — with permission prompts turned off
  (--dangerously-skip-permissions), because the boundary is the container
  rather than the agent's own judgement. You size that boundary once in the
  repo's config; see
  Running an agent without prompts
  for what it does and doesn't cover.
• One shared state layer per repo — package-manager caches, the JetBrains
  config, the Chrome profile pool, ~/.ssh and Claude's login live in a shared
  dir bind-mounted into every one of the repo's containers. Branches running in
  parallel draw on one warm Gradle or pnpm cache and one set of tool settings
  rather than building each from scratch, and the state outlives
  jailbee destroy / jailbee new — while nothing a container does reaches
  your host's own dotfiles.
• Fast, cheap containers — copy-on-write clones of one golden image; a live
  TUI dashboard (jailbee dashboard) or Qt GUI dashboard (jailbee gui) spans every repo.

Getting started

JailBee needs a Linux host running Incus. Install the CLI with
uv or pipx —
JailBee is an ordinary PyPI package and needs neither at runtime, but
Ubuntu 24.04+ refuses a bare pip install into its system Python:

uv tool install jailbee      # or: pipx install jailbee

For the optional Qt GUI dashboard (jailbee gui), add the gui extra:

uv tool install 'jailbee[gui]'      # or: pipx install 'jailbee[gui]'

Host setup — Incus, firewall, UID mapping, kernel keyring limits — is a
one-time job with a few moving parts. Follow Installation
end-to-end first. Then, from the repo you want to manage:

jailbee config init          # write .jailbee/config.yaml
jailbee doctor               # sanity-check host + config
jailbee init                 # create Incus profiles, ACL, bridge
jailbee base build           # build the golden image (one-time, ~10–15 min)
jailbee new feat/my-branch   # spin up an isolated env for a branch

See Getting started for the full first-run
walkthrough.

Shell completion

Install Typer's completion script once per shell:

jailbee --install-completion

Restart the shell, and TAB completes commands, options, and:

• container names on every command that takes one (jailbee shell, jailbee destroy,
  jailbee git push, jailbee ide, …) — short names, from the containers that exist in
  the current repo
• branch names on jailbee new and jailbee retarget, from the host repo's local branches
• snapshot tags on jailbee snapshot restore and jailbee snapshot delete, from the
  container already named on the command line
• fixed values for --format, --layer, --attach and --user

Completion looks for .jailbee/config.yaml in the current directory, the same
default the commands themselves use; elsewhere it offers nothing. Unlike the
commands, it does not honor --config/-c, so e.g. jailbee shell -c /other/repo/.jailbee/config.yaml <TAB> still completes against the current
directory's containers, not the repo the flag points at.

Documentation

Setup — get JailBee running:

Daily use — working with containers:

Reference — the details:

Meta — project internals:

License

jailbee is free software, released under the GNU General Public License v3.0
or later (GPL-3.0-or-later). See LICENSE for the full text.

Copyright © 2026 GISGRO Oy.