jailbee 1.7.4

JailBee gives each git branch its own Linux development environment. Run several full stacks on one host — services, databases, Docker, browsers and IDEs — without branches competing for ports or Docker names. The environments are Incus system containers: each has its own userland and network stack and shares the host kernel, which makes them far lighter than VMs.

That makes parallel coding-agent work practical: give each attempt its own working tree and runtime, see from the terminal dashboard which Claude Code session needs you, and bring commits back through a local git bridge. The same workflow serves development and review without an agent.

The CLI is jailbee, or jb for short. It needs a Linux host with Incus. A repo's .jailbee/config.yaml describes its environment, so JailBee is project-agnostic — built at GISGRO, usable with any stack.

See it work

▶ JailBee 1.7: the 3-minute tour

See what a container per branch gives an agent and how the terminal dashboard helps you manage several at once. For the complete create → code → merge → destroy workflow, watch the end-to-end demo.

What you get

• A whole stack per branch. Each container runs its own services and, when enabled, its own Docker daemon; a browser inside it reaches that branch's app on localhost with no port forwarding. Provisioning and autostart are configured once and baked into a reusable golden image — general development tools by default, language stacks and Docker opt-in. On a copy-on-write backend such as btrfs, new environments and snapshots are cheap. Stacks · Storage

• A local git workflow. jb git push and jb git pull move commits between host and container without a round trip through GitHub; jb git merge merges one container's branch into another, and jb fork starts a new environment from a container's committed work. Submodules initialized on the host travel with the repo, and jb pr can open submodule PRs before the superproject's. Git bridge

• A terminal dashboard for parallel work. Bare jb opens the TUI. It spans every registered repo, shows git and resource status, and tracks Claude Code's state, recent tool calls and messages. Attach a session, inspect a diff, open a PR, or start and stop containers from the same view. Claude Code has a dedicated integration; Codex, Gemini, Aider, OpenCode and Grok presets are best-effort starting points. For other providers' models, claude-jb routes Claude Code through a LiteLLM proxy container. Agents · Claude Code through LiteLLM

• Explicit network policy and a GitHub outbox. Strict mode is the default: a destination IP allowlist, optionally per TCP port, filters container traffic, and an HTTP(S) egress proxy adds hostname rules with wildcards. Loose mode lifts the allowlist. Agents stage proposed PR and issue changes in an outbox for you to inspect and publish with the host's gh; pair it with a read-only container token. Security and limitations · Outbox commands

• Desktop tools inside the environment, local or remote. Launch a JetBrains IDE, Chrome, Firefox or a configured app inside a container with its window on your Wayland desktop; declare host devices and forwarded services (adb, say) when a project needs them. Optional SSH access exposes the TUI and policy-controlled commands, and remote GUI apps run over waypipe ssh or a shared RDP display. GUI apps · Remote GUI

• Reusable state, personal settings outside git. Shared caches and agent settings outlive individual containers, and credential groups share one Claude login across repos — in JailBee-managed directories, never your host ~/.claude. Environment settings live in the repo, personal defaults in ~/.config/jailbee/global.yaml, and host-local repo overrides in ~/.config/jailbee/repos/<prefix>.yaml. Configuration layers · Credential groups

JailBee earns its place when the runtime is the hard part: several services, Docker stacks, desktop tools or agents in parallel. If worktrees alone solve your problem, you may not need it — see Who JailBee is for for trade-offs and alternatives.

Getting started

Prepare the host

Install the CLI with uv or pipx (Python 3.12+):

uv tool install jailbee      # or: pipx install jailbee

Incus, a storage pool and UID/GID delegation are host setup, separate from the Python package: follow Installation, which also covers the firewall and kernel-limit adjustments some hosts need. Then run jb setup for shell completion, the network-refresh user timer and, optionally, JailBee skills for agents on the host.

Try it without a repo config

From any git repo with a fetchable upstream and no .jailbee/config.yaml:

jb new work                 # create a scratch environment
jb                          # open the terminal dashboard

Scratch mode (on by default) synthesizes a config, creates the repo's Incus profiles and, on an interactive terminal, offers to build a scratch image that later scratch environments reuse. The image carries the configured tools; your app's own stack is set up in the next step.

For a local-only repo, jb new work <local-branch> starts from an existing committed branch and skips the upstream fetch. For a directory that is not a git repo, jb new --mount work shares the host directory read-write into the container instead of cloning it. Scratch configuration

Configure a repeatable project environment

From the repo you want to manage:

jb config init              # generate .jailbee/config.yaml
# Edit the config: enable the stacks and integrations your project needs.
jb doctor                   # check host prerequisites and config
jb init                     # create the repo's profiles, ACLs and shared dirs
jb registry up              # only if the project uses the registry mirror
jb base build               # build its reusable image; allow several minutes
jb new feat/my-branch       # create the branch environment
jb                          # manage it in the terminal dashboard

Projects that enable Docker, ECR or extra registries need the mirror running before their first strict-mode jb new; others skip jb registry up. Add provisioning and autostart steps for your dependencies, database and dev server — Getting started walks through a complete config and a typical day. If you tried scratch mode in the same repo first, see Scratch configuration for keeping its containers under the new config.

Besides the TUI, jb console offers an interactive command prompt, and uv tool install 'jailbee[gui]' adds an optional Qt dashboard (jb gui).

Know the boundary

JailBee uses unprivileged system containers that share the host kernel. It is a workspace boundary, not a hostile multi-tenant one. Before leaving an agent running without permission prompts, review what its environment can reach:

• Working trees and mounts. Clone mode gives the container its own working tree; --mount shares the host's. A clone still borrows Git objects from the read-only host-source mount. Shared caches, agent settings, writable host mounts and — by default — the repo's .local/ directory are visible across environments, and container snapshots do not roll back bind-mounted data.
• Credentials and host services. Readable token files can be copied. GPG integration mounts the host's ~/.gnupg read-only, secret keys included, and a forwarded agent socket can sign or authenticate even through a read-only mount. Devices, desktop sockets and port forwards extend the container's reach into the host; attach only what you need.
• Network policy. The NIC ACL filters by IP, not hostname or HTTP path, and different hosts can share an allowed IP. Hostname wildcards apply only through the HTTP(S) proxy. Host sockets and declared port forwards bypass the ACL.
• GitHub publication. The outbox is a review step, not an enforcement point: a write-capable token inside a container can publish directly. Use a read-only token.

Security and limitations, especially Running an agent without prompts, covers the controls and their limits.

Updates and documentation

After updating the CLI package, re-run jb setup. jb upgrade --dry-run lists the registered repos whose image or profiles the release's upgrade notes say to rebuild; jb upgrade runs those steps without restarting development containers or dockerd, and names anything that still needs a restart.

The full, searchable documentation is at jailbee.gisgro.io/docs.

For contributors: Contributing, Manual testing, and Releasing.

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.