JailBee

An agent needs the network to work, so the question is never whether it gets out — it is how wide you leave the entrance. That is what jailbee net strict|loose sets.

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.
• 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.
• Network modes — per-container egress allowlist with strict and loose policies (jailbee net), safe for unattended agent runs.
• 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:

uv tool install jailbee

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

uv tool 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.