Commands¶

The terminal dashboard's container details panel (v) reads top to bottom. One summary line says what the container is doing: its state and any background job, IP, PR and issues, the agent, and busy processes. A running container with a fixed limits.memory also shows its memory use as an htop-style bar ([mem||| 3.0G/8.0G]) at the right end of that line, coloured by the free share like the system status row; it is left out when the line has no room for it. A running container adds up to two lines under it, labelled cpu and mem (the labels are dim), its top three processes by CPU and by resident memory, grouped by process name with xN when several share a name. When present, a separate highlighted line below it lists exceptions: loose networking and its deadline, attached optional mounts and their deadlines, and container-level egress overrides. Then a git table lists the container's own tree and one row per changed submodule, with commits ahead (↑) and behind (↓), the committed diff against the base, the working-tree diff, and the merge prediction (plus the diff against the host's checked-out HEAD when the note column has room). A dim footer line holds what no column shows: a memory-limit override and, for a fork, its source; it is left out when there is nothing to say (mode and credential group are table columns). Unchanged submodules are omitted; ? means the probe could not determine a value. Nothing is cut: a line too long for the panel continues on the next line, and a card taller than the room it gets shows a window of its content with a scrollbar on its right edge. Scroll it with the wheel over the card, PgUp/PgDn, or a click on the scrollbar; the position resets when the selection moves. A repo card scrolls the same way through its notices.

The panel's height is yours to set: +/- make it a row taller or shorter and = returns it to the built-in height; with the mouse on, drag the panel's top border. The table always keeps five rows and its header, and the panel at least two rows. The height is remembered with the rest of the view.

In-container outbox commands¶

Inside a non-child container, stage GitHub proposals with jailbee issue create|edit|comment|labels|assign|state and jailbee pr comment|reply|description|source. jailbee issue assign ISSUE|@REF takes --me (the publishing account, @me), --unassign-me, and repeatable --add LOGIN / --remove LOGIN; at least one is required. Use --body or --body-file; issue commands accept --repo (default .), while PR source and new descriptions accept --repo owner/name. jailbee pr source --ref REF --sha SHA also accepts --head as an alias for --ref; new PRs need a description body.

An omitted PR selects exactly one actual container binding (primary, stacked, imported-head or submodule), independent of the checkout branch or detached HEAD. With multiple bindings, name the PR number. Host creation, start and PR bind/unbind operations refresh a minimal read-only snapshot at /opt/jailbee/metadata/bindings.json; existing containers acquire it on jb start without rebuilding the golden image. An unavailable snapshot never falls back to gh pr view on the current branch. A numbered command without a matching binding uses the current repository for its explicit number.

jailbee pr description [N] updates the bound existing PR by default. It requires an explicit replacement body via --body or --body-file, including when only the title is intended to change. Title-only staging is refused: automatically copying the current body could overwrite later edits when the proposal is published. An explicitly empty body remains allowed. With no bindings it stages a new PR; --new explicitly requests a new description only when the binding snapshot is readable and empty. Any binding, including one for another repository, refuses --new. New repository discovery uses read-only gh repo view without requiring an existing PR; --repo owner/name overrides it. --new writes pr: null: it is a proposal, not a host-side force-create switch. The host can resolve a null PR to an existing binding, so --new must not bypass bindings. Both outboxes cap pending manifests at 20; issue batches cap actions at 100.

Use --batch NAME to collect actions, jailbee outbox ls [--json] and jailbee outbox show issue/NAME or pr/NAME to inspect staged proposals, jailbee outbox submit NAME --kind issue|pr to submit a batch, and jailbee outbox discard NAME --kind issue|pr to discard a draft. Drop a staged proposal with jailbee outbox drop issue/NAME or pr/NAME. For issue batches, create with --ref REF and address it later as @REF; expected values come from that earlier create. Existing issue changes fetch current state for host staleness checks.

Inline reviews use jailbee pr review add N --file PATH --line LINE --body TEXT followed by jailbee pr review submit N; generic outbox submit refuses review drafts. Review add and submit fetch the PR head and refuse if it differs from the first comment's anchor; submit never replaces that anchor. Discard with jailbee pr review discard N. None of these commands publish to GitHub; a human inspects and applies on the host. Do not write outbox files or create outbox directories by hand. Children cannot stage GitHub writes: send the orchestrator exact content using jailbee inbox send message --text "...", or --kind question when a result is needed.

Inside a container¶

Since 1.8.1 every container has a small jailbee (the host's code, mounted read-only at /opt/jailbee/app). Only these commands work there; everything else is host-only:

• jailbee --version
• jailbee config validate (configuration)
• jailbee service ... (Services)
• jailbee inbox ... (orchestration)
• jailbee issue ..., jailbee pr ..., jailbee outbox ... (outbox commands)

The terminal dashboard container menu offers Autostart → (u): Re-run… (r), Status (T), Cancel… (C), and Profile… (p) when applicable. The re-run picker puts failures first and asks for confirmation; failed or interrupted outcomes also mark the container row. Services… (V) on running containers lists services and offers start or stop/restart as appropriate, refresh and logs; an empty list is reported. Entries honor remote SSH policy; elevated service refresh may require the host. These new menus are terminal-only; Qt is unchanged.

Services¶

Inside a container use jailbee service [ls] [--json], jailbee service start|stop|restart|refresh [SERVICE...], or jailbee service logs [SERVICE] [-n N] [--follow]. Group option --repo PATH selects a repository path; otherwise discovery starts at the current directory. jailbee service plan [SERVICE...] --op start|restart|refresh --json exposes the execution plan.

On the host use jb service ls [CONTAINER] [--json], jb service start|stop|restart|refresh [CONTAINER] [SERVICE...], or jb service logs [CONTAINER] [SERVICE] [-n N] [--follow]. Omitted values use a terminal picker, otherwise the command reports candidates. Definitions always come from the container worktree, not the host checkout.

Automatic startup uses selected services (new --services, profile services, or orchestration spawn/restart --services). The repo can position startup with reserved autostart.on_start entries {stage: services}, optionally with services: [names]; these do not broaden the selection. Slots after a detach boundary run detached. See placement and fallback rules.

Start includes dependencies and waits for readiness; stop does not stop dependents. Restart cascades only over restart: true edges. Refresh prepares only named services before restarting them and their cascaded dependents; start and restart never prepare. An elevated container refresh exits 3: ask the orchestrator or run jb service refresh CONTAINER SERVICE... on the host. Elevated refresh pauses an idle managed agent and resumes its session after restoration, including after an ordinary prepare failure. --force skips only the idle check; use it only when work has stopped. Host --yes consents to foreign agents remaining active during elevation, not to interrupting work. Restricted SSH cannot run service refresh, even with network and mount unlocks; run it on the host. Logs use tmux scrollback, not durable or byte-perfect capture: a line matching the exact tmux control-protocol snapshot trailer can truncate the snapshot or end following.

Runtime arguments¶

jailbee service start and restart accept repeatable --env KEY=VALUE and arguments after --, for exactly one explicitly named service. On the host, put the container name first. Arguments require services.<name>.args: true and are passed to run as positional parameters. For example, use run: './scripts/dev/restart "$@" && exec tail -f /dev/null'.

Overrides are one-off by default. --persist saves supplied arguments and merges supplied environment values into the persisted defaults. A plain restart uses those defaults again; --reset-args clears persisted arguments and environment before applying other options. Status displays environment keys, not values; avoid putting secrets in positional arguments.

Status and log queries¶

A service may define a status shell command and status_timeout (default 5 seconds, minimum 1). service ls reports its result without changing lifecycle state: JSON-object output is shown as status plus a short detail, other output uses the first nonempty line, and failures/timeouts report status: error or status: timed out. Status probes are cached briefly.

service logs reads tmux scrollback, not durable logs. -n N defaults to the last 30 lines. Repeat --grep PATTERN or --filter NAME to select matching lines (the union of matches); filters are defined in services.<name>.logs.filters. Queries scan all retained history, then -n limits the last N matches before context expansion. -B N, -A N, or -C N include surrounding lines; overlapping or adjacent ranges merge, and gaps are separated by --.

--wait PATTERN waits for new complete output and accepts -B, -A, or -C context; it cannot be combined with grep, filters, or follow. Its boundary is successful control-client attachment to the tmux output stream, not command invocation, and short setup output before attachment may be missed. For a one-shot line, start the wait in the background before triggering the action; starting a background process alone does not guarantee it has attached. If the action already ran, query retained history instead, for example jailbee service logs api --grep 'ready' -n 5 -A 40. Context before a wait match may omit a short setup gap. Output stops after two seconds of silence. --timeout is valid only with --wait, defaults to 300 seconds, and 0 means unlimited. Exit codes are 0 for a match, 1 for timeout, 2 for invalid input, and 3 if the pane becomes unusable before a buffered hit. These queries do not change service state. Each services.<name>.logs.history_limit contributes to the session setting; JailBee uses the maximum across configured services (default 50000 lines, minimum 1000) for windows created later, including future autostart windows. It does not resize existing panes or create durable logs.

Health and waiting¶

A live, ready service is unhealthy when its health command fails or times out. If health is unset, ready is used; with neither there is no health probe. health_timeout defaults to 5 seconds. Status reads cache probes for five seconds; JailBee never automatically restarts an unhealthy service. Use service ls and service logs to diagnose it, then restart it explicitly.

Inside a container, jailbee service wait api --until ready waits for a state; on the host use jb service wait CONTAINER api --until ready. States are stopped, starting, ready, failed, exited, and unhealthy. Waiting for unhealthy also matches stopped, failed, or exited; with multiple services the first matching service wins. --json prints the matching status. --interval defaults to 10 seconds (minimum 1); --timeout defaults to 0 (no limit). Exit codes are 0 for a match, 1 for timeout, 2 for invalid input, and 3 when waiting for ready encounters stopped, failed, or exited. Each tick performs a synchronous fresh status read before checking the deadline, so an in-flight scan can exceed the overall timeout. Lock acquisition and the probe itself are each bounded separately by health_timeout, so a scan may include both waits.

Global repository option¶

--repo PREFIX runs a command in that registered repository instead of the current directory's repo. PREFIX is an exact registered prefix, not a path. Without it, local commands keep their usual cwd / scratch behaviour. It may precede the command (jb --repo x chrome feat), appear inside its command path (jb net --repo x egress add pypi.org feat), or follow its arguments (jb chrome feat --repo x). Only one global --repo is accepted; arguments after -- are passed through unchanged.

Commands with their own --repo keep its existing meaning when written after the command name: net egress add / rm, net refresh, net unregister and console. Put the global selector before that name (or before the group), for example jb --repo x net egress add pypi.org --repo. The global selector cannot be combined with -c / --config.

Run these management commands on the host (or through the configured remote entry point), not inside a development container. Container arguments accept short container names, full prefixed names or aliases. Brackets in the syntax mark optional arguments: required values left out are resolved through a terminal prompt or, where safe, a single candidate; otherwise the command exits with a message. Listing commands generally treat an omitted target as "all" rather than asking.

Before any PR agent run, JailBee asks whether to generate the configured PR title/ description and/or branch-name proposal with the named agent. One answer covers both features; No is the default because generation costs time/money and sends code to a model. --ai authorizes generation without asking; --no-ai skips both features without asking (combining them is exit 2). Without a TTY, or with JAILBEE_NONINTERACTIVE, generation is skipped with one stderr hint unless --ai is given. --yes and --description do not authorize an agent run. Disabled pr.ai_description / pr.ai_branch settings stay disabled even with --ai. Existing outbox descriptions are used without this question. The policy also applies to jailbee submodule pr push, the terminal dashboard and remote SSH; Qt opens PR flows in a terminal for the same question.

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.

PR source selection¶

jailbee pr push <name> on a terminal offers the container's own branch first, then pending source PR proposals from its outbox, labelled with title, source head, base and manifest file. Picking one runs the same confirmation, validation and receipt handling as --source-manifest <file>. Cancel publishes nothing. An own-branch description is not a separate source; published proposals awaiting cleanup are not offered again. Without pending sources there is no extra question. The dashboards' Create/update PR offers the same choice: the terminal frontend uses the CLI picker; Qt shows a native choice and opens a terminal for source publication confirmation.

Off a terminal, the command keeps publishing the own branch and prints a pending source count on stderr, with --source-manifest <file> and jailbee outbox <name> hints. Explicit --source-manifest skips the picker. So does any own-branch option (--title, --body, --base, --branch, --as, --pr, --stacked, --retarget/--no-retarget, --ready/--draft/--no-draft, --description, --web, --ai, --no-ai, --no-outbox, --no-submodules), but the count is still printed. Only --config, --force and --yes preserve the choice; --force and --yes carry over to the selected manifest. An unreadable or invalid outbox never blocks the own-branch flow. jailbee submodule pr push is unchanged.

Console¶

jailbee console opens an interactive jb[<prefix>]> prompt on your own terminal. It starts in the registered repository containing the current directory, or asks which one (straight in when exactly one is registered); --repo PREFIX picks one explicitly. At the prompt, type JailBee commands without the jailbee prefix, with tab completion and history. repos lists the registered repositories, use [PREFIX] switches repository (bare use reopens the menu), dashboard opens the dashboard, help lists the commands and exit (or Ctrl-D) leaves. A line's global --repo PREFIX runs only that command in another repo; it does not change the prompt's selected repo (use does). Locally it is unrestricted: it applies no remote.ssh policy. It is an interactive entry point only, so it cannot be run as a one-shot command over remote SSH (there the console is ssh -t … console, restricted by policy; see below).

Bare jailbee (or jb) on a terminal opens whatever default_command names — the dashboard by default. Off a terminal it prints the help text and exits 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 takes the complete fingerprint printed by add or ls; left out, it is chosen from the stored keys on a terminal (even when only one is stored) and is exit 2 off one. 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] [--console/--no-console] [--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, so an invalid combination is reported the same way a broken config file is. --console with --commands disabled is valid: console-local navigation remains available, but JailBee commands are refused. --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 --console --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 console [--repo PREFIX]
ssh -p 8022 jailbee@localhost help
ssh -p 8022 jailbee@localhost repos
ssh -p 8022 jailbee@localhost COMMAND [ARGS...] [--repo PREFIX]
ssh -p 8022 jailbee@localhost -- --repo PREFIX COMMAND [ARGS...]

The old shell spelling of the remote entry point (remote.ssh.shell, default_entrypoint: shell, serve --shell) still works until 2.0.0; jailbee config migrate --apply renames it. Only the exact ssh … shell and ssh … shell --repo PREFIX forms mean the legacy console; ssh -t … shell NAME --repo PREFIX runs jb shell NAME in a container.

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 console to open that entry point instead; an explicit help lists enabled forms and allowed command paths. repos lists the registered prefixes and roots visible to the session (it requires exec: true). 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 console --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 without excluded repositories, help then runs the real python -m jailbee --help in the current repo root. In allowlist mode, or with excluded repositories, it instead renders a filtered second panel, "Allowed Jailbee commands", listing allowed paths with their 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.

One-shot SSH execution accepts every JailBee command the remote console does, under the same command policy and host restrictions. The global --repo PREFIX follows the placement rules above; the old -- --repo PREFIX COMMAND form still works. The registered root becomes the command's working directory. Without a selector, one visible repo is used automatically; with several, ssh -t shows a picker and a non-PTY call exits 2 naming the candidates. Command help does not need a repo or open a picker. console --repo PREFIX also takes an exact registered prefix; a console line's global selector is temporary, just as it is locally. Excluded repos are unavailable to selectors, pickers and repos. 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, adding an egress rule is a host command unless remote.ssh.network is on, while removing one is always allowed (container scope only; --repo is always refused). Each new SSH channel gets the current validated effective policy; a console or dashboard already running keeps its startup command-policy snapshot. Mount authorization is an exception: each mount also checks the current global.yaml policy, so removing a permitted root can block new mounts even in an older session. 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.

GPG keys over remote SSH¶

To decrypt or sign inside containers using keys on a Linux or macOS client, opt in on the server in ~/.config/jailbee/global.yaml:

remote:
  ssh:
    gpg: true

Keep gpg.enabled: true in each participating repo. Run jb restart <container> once for existing containers to install the new read-only switch mounts; no profile apply or golden-image rebuild is needed. The local host agent still works when the SSH service has never been started. Import the client's public keys into the host's ~/.gnupg (gpg --import public-keys.asc): containers read that keyring, not the client's keyring.

On the client, start the agent and ask GnuPG for its restricted extra socket:

gpgconf --launch gpg-agent
gpgconf --list-dirs agent-extra-socket

Use the command's actual output. Typical paths are /run/user/<uid>/gnupg/S.gpg-agent.extra on Linux and ~/.gnupg/S.gpg-agent.extra on macOS with Homebrew GnuPG or GPGTools (expand the home directory to its absolute path). Add one line to the SSH Host block used to reach Jailbee:

Host jb
    HostName your-host
    User jailbee
    Port 8022
    RemoteForward /jailbee/gpg-agent /path/from/gpgconf/S.gpg-agent.extra

Open ssh -t jb dashboard or ssh -t jb console. While the forward is up, every gpg.enabled container with the new mounts uses the client's agent, not just the container you enter. The newest live forward wins; when it closes, the previous live forward takes over, or the host agent resumes. Pinentry and card touch prompts appear on the client. SSH_AUTH_SOCK and SSH authentication inside containers keep using the host agent. No private key is transferred through this forward. Cancelling the forward without closing SSH also restores the previous agent. Only one SSH server process per host user owns the switch; a concurrent diagnostic server on another port refuses GPG forwards rather than interfering with the active service.

For a smartcard, run gpg --card-status on the client if its agent has not learned the card yet. Software keys need no card-learning step. GnuPG 2.4 may print problem with fast path key listing: Forbidden - ignored through the restricted extra socket; this does not prevent decryption.

Treat this as host-wide authority to request operations. When GPG is a gate for secrets, prefer a smartcard with a touch policy, for example ykman openpgp keys set-touch dec on and ykman openpgp keys set-touch sig on on the client. With a software key, or a card without a touch policy, the client agent's passphrase cache (default-cache-ttl) can let any participating container decrypt without a prompt while the cache is warm. Client-only private keys stay on the client; any private keys already stored in the host's shared ~/.gnupg remain readable there. See Security.

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 --force '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, with the highlighted container as the source. The Qt dashboard starts jailbee merge and leaves target selection to the CLI prompt. The terminal dashboard picks the targets in the table itself, with every column in view: the source rows show ◆, rows that cannot be a target (another repo, stopped, mount mode) are dimmed and the cursor skips them. Entry keeps the highlighted row if it is eligible; otherwise it moves to the next eligible row, or the previous one if none follows. Space toggles a target's mark without moving the cursor, Enter runs jailbee merge <sources> --into <target>… over the marked targets — or the highlighted row when none is marked — and Esc cancels. A line under the table names the sources and targets throughout. Bulk Merge into… enters the same mode with the marked containers as sources (they must be in one repo); Esc gives the marks back, and a successful merge unmarks its sources. A source that disappears in a refresh ends the mode. The equivalent !merge command follows the selected-container default described above. Fork… and Rename… ask for the new container's name and the alias: inline in the terminal dashboard ([f] and [R] in the container menu), where Fork runs jailbee fork --background and Rename jailbee rename (an empty alias clears it); the Qt dashboard opens jailbee fork <container> or jailbee rename <container> in a terminal, where the CLI asks. Rename starts with the current alias, or the container's short name when no alias is set, so a suffix can be appended directly. Ctrl-R clears the name immediately in the terminal dashboard's rename prompt and in the CLI prompt used by Qt (the CLI offers the shortcut only when an alias exists). An empty Enter response also clears the alias in the terminal dashboard, but not in the CLI. The single-container menu has only Rename…; Clear name is available in the multi-selection menu and skips containers without aliases. That menu leads with Merge into…, then base updates and sending commits to the host, followed by lifecycle, network and clear-name actions, with Destroy last. The terminal dashboard alone offers Clear outbox… ([X]) in the container menu and the N selected menu. It always asks for confirmation with No first, even when general confirmations are disabled, then clears eligible proposals in that container or the marked eligible containers. Protected or changed proposals remain; Qt does not offer this action. Change base branch asks for the base itself: inline in the terminal dashboard, in a dialog in the Qt dashboard, with the host's other local branches as suggestions. A branch the host does not have is refused. The dashboard then runs jailbee git retarget with both the container and the base.

The commands that exist for the text they print — pr, git push, git pull, git diff, git retarget, 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.

--foreground (GUI-only) keeps it attached to the terminal. The TUI's --interval/-i, --git-interval and --no-git are accepted by all three commands but deprecated and ignored (see Refresh).

AI activity age¶

The dashboard AI age measures time since the latest real agent event across that agent's live sessions, not time in its current status. Assistant text, thinking and tool calls, and user tool results count; prompts, metadata and file modification times do not. Missing, malformed or future event dates are ignored; without a valid event date the age is unknown (no status-age fallback). Status symbols and urgency still describe the most urgent live session. The details panel shows the selected activity session's status duration separately, for example active 14s ago (busy for 23m); an idle agent whose last event is as old as its idle time reads just active 25m ago. Recent-idle highlighting uses event age too. Both ls agent columns retain status duration; the JSON since field still records status changes.

Refresh¶

Every dashboard — jailbee dashboard, jailbee tui, jailbee gui — shows what one shared background service (jailbee _state-service) gathers. It starts on demand and exits 30 seconds after the last dashboard closes. Its pace is set by dashboard.refresh in the global config; its log is ~/.local/state/jailbee/state-service.log. --interval/-i, --git-interval and --no-git are deprecated: they print a warning and have no effect. The Qt Refresh menu has only Refresh now. A minimised window, or a dashboard whose terminal is running jailbee tmux or jailbee shell, does not make the service gather.

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 offer the same single-container actions. Table also supports multi-selection and a bulk action menu; Cards selects one container at a time, and right-click selects that card before opening its menu. 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) and card style (Compact or Grid),
• enabled columns, their order, and the table's column widths,
• folded and hidden repositories, and whether empty repositories are shown,
• sort field and direction.

View preferences are stored separately for the terminal and Qt frontends.

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

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.