jailbee 1.6.0

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. Release announcements are at jailbee.gisgro.io/news.

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.

See it work

▶ Watch the whole flow

What the full clip shows, end to end. A branch gets a container of its own, cloned from the golden image with the app's dependencies synced, its database seeded and its dev server already listening on port 8080. A coding agent gets a window inside it and is asked for a /health endpoint with a test; the human detaches, checks the running service from outside, and comes back to find the work committed. jb git pull brings that commit onto the host as a merge — asking before it destroys anything — and jb destroy throws the container away as its own deliberate step.

Every command and every line of output is real. Two stretches of the clip are sped up and say so on screen; nothing else is edited.

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), Chrome or Firefox (jailbee chrome, jailbee firefox), or any other app registered under apps: (jailbee apps run <name>), from inside a container onto your Wayland session.
• Host sockets, shared — the Wayland display and (with gpg.enabled) the gpg-agent are attached to every container, PulseAudio and D-Bus on request (gui.audio, gui.dbus), 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 and use it from inside.
• Host services, forwarded in — declare host_ports: [{ name: adb, port: 5037 }] and every container of the repo reaches that host service on its own localhost, so plain adb devices works inside with no ADB_SERVER_SOCKET juggling. jailbee port adds or removes a forward on one container without touching the config, in either direction — to-host for the rarer case where you do want a container's service on the host.
• 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. jailbee net egress add widens one container's copy of that list — or this machine's copy of the repo's — without editing the committed config, so a host only you need never lands in git; see Egress overrides. An optional work network (jailbee net migrate) gives containers a stable address and switches modes without replacing their NIC.
• Personal settings stay out of git — ~/.config/jailbee/global.yaml holds what is yours on every repo, and a host-local ~/.config/jailbee/repos/<prefix>.yaml what is yours on one (its GitHub token, credential group, extra egress), above the committed .jailbee/config.yaml; jailbee config edit --local edits it.
• First-class Claude Code — opt in with agents.claude.enabled: true and every container gets Claude Code installed, sharing one settings directory across the repo's containers and one login across every repo in its credential group (jailbee account manages the stored logins), while your host ~/.claude is never read. Instructions written once in ~/.config/jailbee/AGENTS.md reach every container's Claude. 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 — to your repo's own standard, if you state one in pr.prompt. 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.
• PR and issue outbox — a container's gh is read-only, so an agent reviewing a PR or triaging issues inside it stages comments, replies, description rewrites and issue changes as JSON manifests instead of posting them straight to GitHub. A human reviews the exact text and publishes it with one confirmation: jailbee review apply and jailbee issue apply (also ls/show/drop), or jailbee outbox to browse both in one place; jailbee ls and both dashboards mark a container carrying pending manifests, and jailbee pr picks up a pending description in place of asking an agent to write one.
• Claude Code on other models — claude-jb runs Claude Code against a LiteLLM proxy that JailBee keeps in its own container, so the same agent can work on a ChatGPT subscription or on any provider you have an API key for, while plain claude stays native. One proxy per account, per-repo route overrides, live route reloads; see Claude Code through LiteLLM.
• Remote access over SSH — an optional, key-only SSH service (jailbee remote ssh enable) opens the dashboard, a restricted console or policy-limited one-shot commands from another computer; host-management commands stay refused. With remote.ssh.gui on, GUI apps launched over SSH appear on a shared RDP display (jailbee display) you open in any RDP client; see Remote GUI over SSH.
• Generic agent support — agents: {codex: {enabled: true}} wires any terminal coding agent into the same mount/egress/install/autostart pipeline Claude Code uses, via a shipped preset or one you write yourself. An agent that declares a skills directory gets JailBee's skills, and one with a headless command can write jailbee pr's title and body (pr.agent). Five presets beyond Claude (codex, gemini, aider, opencode, grok) ship as untested starting points — see Generic agent support.
• One shared state layer per repo — package-manager caches, the JetBrains config, ~/.ssh and Claude's login live in a shared dir outside the containers, set up once per repo instead of once per branch. Most of it is one mount every container shares live — pnpm's store, JetBrains, ~/.ssh, Claude's login. Gradle, Maven and the Chrome profile instead give each container its own private slot seeded from the warmest one: a warm cache without the lock contention one shared ~/.gradle used to cause. Either way 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, alias jailbee tui) or Qt GUI dashboard (jailbee gui) spans every repo, shows what each container's agent is doing, and acts on what it shows: attach a shell or tmux, open the IDE, create or update the PR, update a container from its base, read its diff — without leaving the view that told you it was needed.

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, ACLs, 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.

Trying it without a repo config

Skip jailbee config init and jailbee init entirely for a quick look — cd into any git repo and just run jailbee new work. With no .jailbee/config.yaml in the directory, JailBee synthesizes a config from ~/.config/jailbee/global.yaml's scratch: block, creates that directory's Incus profiles on the fly, and boots the container from a golden image shared by every such directory on the host (alias jailbee-scratch-base). The first time, it asks to build that image (a one-time, few-minutes cost); every later scratch directory reuses it immediately. A directory that isn't a git repo needs jailbee new --mount work instead, since there's no upstream to clone from. See scratch for the config block, and run jailbee config init once the work outlives an afternoon.

Post-install setup

Installing the package puts jailbee and jb on your PATH and nothing else. One command installs the rest:

jailbee setup

It asks about three steps, each idempotent — re-run it after upgrading:

• shell completions for both jailbee and jb (bash, zsh or fish),
• the jailbee-net-refresh user timer, which keeps strict-mode egress allowlists current and expires jailbee net loose --for TTLs,
• JailBee's agent skills for the agents found on your host (opt-in via install_host_skills in ~/.config/jailbee/global.yaml), so they know how to drive jailbee.

jailbee doctor reports any step that is missing. Host prerequisites — Incus, the firewall, UID delegation — are separate; see Installation.

Shell completion

Restart the shell after jailbee setup, 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

The full documentation lives at jailbee.gisgro.io/docs — the same pages this repository's docs/ holds, indexed and searchable.

Start here:

Project internals — maintainer procedure, kept in the repository:

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.