Commands¶

Compatibility aliases. jailbee claude ls|use|park|rm|group … still works as a hidden alias for the matching jailbee account command, and jailbee new --claude-group for --credential-group; both warn once per invocation. A container labelled user.jailbee.claude_group (the pre-rename spelling) is read but never written, and is not warned about — nobody is being asked to retype it. All are removed in 2.0.0.

Remote SSH service¶

The optional SSH service exposes JailBee, not a host shell. Installation and startup are separate opt-ins; see Installation and remote.ssh configuration.

Service and key commands:

jb remote ssh enable
jb remote ssh disable
jb remote ssh restart
jb remote ssh status
jb remote ssh serve

jb remote ssh key add PATH
jb remote ssh key add -
jb remote ssh key add
jb remote ssh key ls
jb remote ssh key rm SHA256:FINGERPRINT

key add reads exactly one plain OpenSSH public key — from PATH, from stdin with - (e.g. cat k.pub | jb remote ssh key add -), or, with no argument, pasted at a prompt on a terminal (one line, no Ctrl-D needed) or read from piped stdin when there is no terminal. It rejects options, certificates and duplicates, preserves the key's comment, and prints <fingerprint> <algorithm> <comment>. key ls uses the same one-line format. key rm requires the complete fingerprint printed by add or ls. New connections reload the key file, so adding or removing a client key needs no service restart; an already-authenticated connection is not revoked.

status prints whether the unit is installed, enabled and active, the configured address and port, enabled entry points, authorized-key count and each detected problem. A deliberately absent, disabled or inactive service and an empty key list are reported without making status fail; invalid config or an unsafe, missing or uninspectable host key produces a nonzero exit. serve runs the same listener in the foreground and is intended for diagnostics. On startup it prints the listening address, the host key's SHA256 fingerprint and a matching connect example. disable preserves global configuration, client keys and the server host key.

serve also accepts one-off overrides of remote.ssh for experimentation, without touching global.yaml:

jb remote ssh serve [--listen ADDR] [--port N] \
                     [--dashboard/--no-dashboard] [--shell/--no-shell] [--exec/--no-exec] \
                     [--commands disabled|allowlist|full] [--allow CMD]... \
                     [--restrict-host/--no-restrict-host] [--files/--no-files]

--files turns on sftp/scp into a container's repo directory for this run (see Security → File transfer).

Every flag defaults to unset, in which case global.yaml decides as usual; only a flag actually given overrides its field, for this run alone. The merged result is validated by the same rules as global.yaml (for example --shell still requires an enabled commands.mode), so an invalid combination is reported the same way a broken config file is. --allow is repeatable, and given at least once, REPLACES the configured commands.allow list rather than appending to it. The systemd service's ExecStart never passes any of these flags. For example:

jb remote ssh serve --port 18022 --shell --commands allowlist --allow ls --allow new

The SSH username is always jailbee. With the default listener port, the accepted client forms are:

ssh -t -p 8022 jailbee@localhost dashboard
ssh -t -p 8022 jailbee@localhost shell [--repo PREFIX]
ssh -p 8022 jailbee@localhost help
ssh -p 8022 jailbee@localhost -- --repo PREFIX COMMAND [ARGS...]

The -- is for the client: OpenSSH keeps parsing its own options after the destination while the next word starts with -, so a bare --repo fails with unknown option -- -.

A commandless ssh -p 8022 jailbee@localhost prints the enabled entry points and exits successfully by default. Set remote.ssh.default_entrypoint in the host's global.yaml to dashboard or shell to open that entry point instead; an explicit help always prints the list. All three entry points are enabled by default, while commands.mode independently governs console and one-shot commands across the console and dashboard; exec: false disables one-shot execution only. commands.mode: disabled blocks dashboard actions that run JailBee commands, but not dashboard navigation or the console's local navigation. dashboard and the remote console require -t; one-shot commands do not inherently require a PTY, though an interactive JailBee command may. Server-written text (this help, and any rejection) uses CRLF line endings whenever the client negotiated a PTY (which OpenSSH does even for a commandless, -t-less login) and plain LF otherwise; child JailBee command output is unaffected either way.

The console starts by asking which registered repository to use — an arrow-key menu when more than one is registered, or straight in if there is exactly one — unless started with shell --repo PREFIX. It offers repos, use [PREFIX] (bare use reopens the menu), dashboard (listed only when enabled), help, and exit, rendered as a Rich panel styled like jb --help's own. In full mode, help then runs the real python -m jailbee --help in the current repo root, so the console shows exactly what a local jb --help would. In allowlist mode it instead renders a second panel, "Allowed Jailbee commands", listing each allowed path with its own one-line help. In disabled mode it prints a one-line note instead. Esc, Ctrl-C and Ctrl-D all cancel the menu (exiting the console at startup, returning to the prompt from use). Every other line is an allowed JailBee command, tab-completed word by word (e.g. git p<Tab> offers pull/push). A hidden alias (merge, pull, push, ...) is policy-checked against the public command it aliases, so allow: [git merge] also permits typing merge. A public group's own help — git, or git --help/-h — is permitted on its own whenever some command under it is allowed (or in full mode); the bare top-level --help/-h works the same way. Unknown commands are rejected before a JailBee child starts. The console performs no shell expansion, pipes, redirection or executable lookup.

Every one-shot command needs --repo PREFIX. PREFIX is an exact registered repository prefix, never a filesystem path; the registered root becomes the command's working directory. The same rule applies to shell --repo PREFIX. See Security and limitations before granting access.

For SSH dashboard sessions, the effective remote.ssh policy is checked before any action that runs a JailBee command, including !, merge, container actions, quick keys, and creation. These actions are blocked by commands.mode: disabled; exec controls only one-shot SSH execution. Dashboard navigation remains available, and console-local navigation remains available while JailBee commands are disabled. The same host-protection rule applies even when command policy is otherwise permissive, unless restrict_host: false was explicitly configured. For the dashboard's Egress panel, net egress ls controls read access and net egress add/rm are checked independently; with the default restrict_host: true, Egress is read-only even when the command policy is full. Each new SSH channel gets the current validated effective policy; a console or dashboard already running keeps its startup snapshot. An upgrade adopting the enabled entry-point defaults can expose the console and command routes on an already-enabled service unless global.yaml disables them; review that policy and authorized keys before upgrading.

Top-level app promotion¶

An apps: entry with top_level: true also runs as a bare jailbee <name> [args…] — equivalent to jailbee apps run <name> [args…], just without the apps run. Everything after the name is passed through unchanged, so another container is named exactly the way apps run names one: jailbee <name> --container <container> [args…], and an argument that starts with a dash needs a -- separator (jailbee <name> -- --some-flag). A bare jailbee <name> <container> does not work — apps run takes the container as an option, so the name is appended to the app's own arguments and the app starts in the default container instead. A built-in command of the same name always wins, and jailbee config validate reports the collision as a config error (it is checked in validate_runtime, so only that command reports it — jailbee doctor and ordinary commands do not) rather than the app silently never being reachable that way. See apps.

jailbee gui / jailbee dashboard --gui¶

The graphical (Qt) counterpart to the terminal dashboard — the same live, cross-repo container view with per-container actions via right-click / popup menus. Requires the optional PySide6 extra:

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

(from a checkout of the JailBee repo: make install, or uv tool install -e '.[gui]')

By default the GUI detaches to the background: the command prints a "Launched jailbee dashboard GUI in the background" message and returns immediately, with the window's stdout/stderr logged to /tmp/jailbee-gui.log (useful if the window fails to appear — e.g. missing PySide6 platform plugins). Pass --foreground to run it attached to the current terminal instead (blocks until the window closes; errors surface directly).

Interactive actions (shell, tmux) open in a host terminal emulator. Set $JAILBEE_TERMINAL to force a specific emulator; otherwise JailBee auto-detects one (x-terminal-emulator, ptyxis, gnome-terminal, konsole, foot, alacritty, kitty, xterm). IDE, Chrome and Firefox launches reuse the same jailbee ide / jailbee chrome / jailbee firefox behaviour; the action menu also lists every other apps: entry as a "Launch <name>" item — dispatched as jailbee apps run <name> --container <container> regardless of top_level, so it launches in the highlighted row's own container whether or not the entry is promoted to a top-level command.

The shared per-container action menu also offers Merge into… when the git bridge is available. It starts jailbee merge with the highlighted container as its source and leaves target selection to the CLI prompt; no target is guessed. In the terminal dashboard, the equivalent !merge command follows the selected-container default described above. Change base branch works the same way: it starts jailbee git retarget with the container and the CLI's branch picker chooses the new base (terminal window in the Qt dashboard).

The commands that exist for the text they print — pr, git push, git pull, git diff, job log — get no terminal emulator: they run inside the GUI and stream their output into a JailBee window with Stop and Copy buttons and the exit code on its status line. The window is non-modal, so the dashboard keeps refreshing behind it and several commands can be watched at once. Stop matters for job log on a live job, which follows the worker's log until it is stopped.

Because that child process has no stdin, whatever the CLI would prompt for is collected in a dialog first and passed as a flag — and only where the CLI would ask: git push's merge/rebase/plain choice when the repo's push.default_action is ask, its source when push.default_source is ask (see Configuration), pr's draft/ready, description and existing-PR-head choices, and a confirmation for git pull, which merges into the host's own branch. Cancelling a dialog dispatches nothing.

Options mirror the TUI: --interval, --git-interval, --no-git, plus --foreground (GUI-only).

Layouts: Table vs Cards¶

A View menu switches the container list between two layouts:

• Table — the original wide, sortable columns view.
• Cards — a width-adaptive card grid; cards re-wrap to fill the window (one column when narrow, several side by side when wide).

Both layouts share the same right-click action menu and selection behaviour. Fresh installs (no prior GUI session) open in Cards.

Persisted state¶

Between sessions the GUI remembers, per-machine, in the same SQLite state DB used for other JailBee state (state.sqlite):

• the selected layout (Table or Cards),
• the table layout's column widths and order,
• the refresh cadence and whether auto-refresh is paused (set via the Refresh menu).

Not persisted: window size and position — that's left to the window manager.

--interval precedence when the GUI starts: an explicit --interval/-i flag wins, otherwise the persisted refresh cadence from the last session is used, otherwise the default of 3s. --git-interval is never persisted — pass it each time it should differ from the default.

For full flag-level detail without jailbee <cmd> --help, the jailbee-usage skill (docs/skills/jailbee-usage/) and its references/commands.md document every command and option.