CLI reference

bb box: Fast boxes for BB threads: list, acquire and release them, and check the backends. Each command’s --help prints what is below.

Command	What it does
bb box doctor	Check each backend’s settings and host, and say how to fix what is wrong.
bb box kinds	List the kinds of box the active backends offer.
bb box list	List a thread’s boxes, or every box with –all.
bb box acquire	Acquire a box for a thread and wait until it answers.
bb box status	Show one box, checking its power state with the backend.
bb box run	Run a shell command in a thread’s box, or with –machine in one of your machines, as its user, and print its output. It exits with the command’s exit code. For a long command, use box_run, which keeps it as a job.
bb box resize	Resize a thread’s box: its cores, memory, disk or GPU, where its backend can, live or with –restart. Parts left out stay as they are, and the disk only grows.
bb box machines	List your machines: boxes you own, kept as BB machines, which no thread ending releases.
bb box machines add	Add a machine of your own: a box of the kind, kept as a BB machine under the name until you remove it.
bb box machines resize	Resize one of your machines: its cores, memory, disk or GPU, where its backend can, live or with –restart. Parts left out stay as they are, and the disk only grows.
bb box machines remove	Remove one of your machines: its box is released and its disk deleted. A machine a thread is working on is refused unless –force. Snapshots you kept are copied first, so they outlive it, unless –delete-kept.
bb box thread	Start a child thread of a thread on one of its boxes, as a BB machine, with the thread’s project.
bb box release	Release a box. Its disk is deleted. A box a thread is working on is refused unless –force. Snapshots you kept are copied first, so they outlive it, unless –delete-kept.
bb box stop	Stop a thread’s box, or with –machine one of your machines, keeping its disk. A box a thread is working on is refused unless –force.
bb box start	Start a thread’s stopped box, or with –machine one of your machines, and wait until it answers.
bb box enrol	Add a ready box that is not a BB machine to BB again, as a thread’s box, or with –machine one of your machines: BB’s installer runs in it as its user. It does not restart, stop or resize the box. It stops only the BB daemon of a machine that BB no longer has. A box whose machine BB still has is left as it is, and recorded as a BB machine. Waits up to 2 minutes for the try.
bb box forget	Forget a box whose backend is no longer in BB Box’s settings: BB Box removes its record and deletes nothing, so a guest that still runs keeps running.
bb box image set	Set a project’s image (049): a script run as root on its kinds’ standard images, for the boxes of the project’s threads, with an optional check run as the box user. BB Box keeps a copy of the files. Setting it changes every new box of those kinds in the project.
bb box image remove	Remove a project’s image (049). Boxes of its kinds in its projects start from the standard images again.
bb box image list	List projects’ images (049): each one’s kinds, projects, how it is baked, where its script came from, and its builds.
bb box image show	Print a project’s image’s script, and its check, as BB Box keeps them (049).
bb box image try	Try a project’s image’s script as a build runs it (049), on a kind it covers, and remove what the try made. It prints each check’s result and the build’s last lines, and exits 1 if one failed.
bb box images list	List the standard images BB Box rebuilds (049): each one’s build and age, why it is due, and what its last rebuild did, most needed first.
bb box images refresh	Rebuild the standard images that are due (049), one at a time, most needed first, and start none after the time limit. A BB script automation runs it each night. It ends with a line per image, and exits 1 if one failed. Should this command end first, the run goes on.
bb box images build	Rebuild one standard image now, due or not, and whatever its last rebuild did (049), and replace it when its trial box passes. –try checks a new build and keeps the old one.
bb box images versions	Show what a rebuild of the standard Linux images would take now (049): upstream’s latest stable Claude Code, Codex, pi, gh and Chrome, each with the SHA-256 it publishes, and the day’s apt snapshot, against this BB Box’s pins.
bb box setup docker	Set up Docker for boxes, as the Box panel’s first run does: on the BB machine that runs BB, or –machine, turn Docker on with the Linux image alone and wait while it builds, usually 5 to 12 min. Where something stands in the way, it gives that machine’s line to fix it. –no-wait starts it and says how far the build is; run it again to see.
bb box docker-check	Check that Docker on a BB machine answers through BB Box’s Docker relay (042), with its version, cores and memory.
bb box docker-build	Build the images a BB machine that hosts Docker boxes lacks there, or has from another layout or with another build of BB’s app, through BB Box’s relay (042). Waits for the build. Building all three needs about 36 GB free there; with less, it does not start.
bb box install-id	Show this install’s ID, which it records on its guests. –set takes back the ID it had before it lost its storage.
bb box config show	Show BB Box’s configuration. –json prints it as a file for config apply, with no secret in it: keep it to set BB Box up again.
bb box config check	Check a configuration file without saving it. –test also runs the doctor of each backend in it that is on, within 30 s each.
bb box config apply	Save a configuration file as BB Box’s whole configuration, then rebuild what changed. A revision in the file must be the current one; a file without one, or –replace, saves over what is there, as when setting BB Box up again from an export.
bb box config migrated	Show the copy of BB’s settings BB Box kept when it moved them into its configuration. –remove removes it.
bb box backend list	List the configuration’s backends, in the order a new box tries them: each one’s switch, state, kinds, boxes and last check.
bb box backend types	List the types of backend BB Box has: what each is for, what setting it up needs, the kinds it makes, and its setup guide and scripts in BB Box’s repository.
bb box backend fields	List a backend type’s fields, or a backend’s with their values now: each key, what it takes, whether it is a secret, and the first line of its help. Secrets show only as set or not.
bb box backend add	Add a backend, on unless –off, through the same checked save as the settings page, then run its checks. Secrets come only from a dotenv file or stdin. Exits 2 when it saved and its checks failed.
bb box backend set	Change a backend: its fields, secrets, switch, name or warm boxes, through the same checked save as the settings page, then run its checks. Exits 2 when it saved and its checks failed.
bb box backend remove	Remove a backend: its settings, its secrets, which cannot be got back, and its warm boxes. Refused while it has boxes, as on the settings page. Asks for –yes.
bb box backend host add	Add a host to a backend whose hosts are set up alike, such as a Mac to Tart. The SSH host pool lists its machines in its machines field instead: bb box backend set ssh-pool –add-line.
bb box backend host set	Change a backend’s host: its fields, or its switch. Off, it takes no new boxes, and its boxes keep working.
bb box backend host remove	Remove a host from a backend. Refused while it has boxes, as on the settings page.
bb box kind set	Change a kind: whether it is offered, its presets’ sizes, its default preset, its largest custom size, its spare boxes, its GPU when not asked for, or make it the default kind, through the same checked save as the settings page. Sizes and the GPU change new boxes only.
bb box option list	List the general and Monitor options: each one’s value now, its default, and what it does.
bb box option get	Show one general or Monitor option: its value now, its default, and what it does.
bb box option set	Set general and Monitor options, such as monitor.enabled=false, defaultKind=linux or general.snapshots.ceilings.<backend>=7.50, a ceiling on a backend’s paid snapshots, in one checked save, as the settings page saves them. bb box option list lists them.
bb box option unset	Give general and Monitor options back their defaults, in one checked save. general.tailnet.mode turns the tailnet off and clears its client.
bb box snapshot take	Take a snapshot of a thread’s box, or with –machine one of your machines: its disk, or with –memory its disk and its memory where its backend can. Waits until the backend confirms it. A box holds as many as Settings, Snapshots allows, 5 unless set.
bb box snapshot list	List the snapshots of a box, of a thread’s boxes, of your machines with –machine, or with –all every snapshot BB Box records, those of released boxes too.
bb box snapshot delete	Delete a snapshot of a thread’s box, or with –machine one of your machines, by its name or ID, and wait until its backend confirms. An incomplete one is cleaned up on its host. A box that is gone is named by the ID bb box snapshot list –all gives.
bb box snapshot restore	Restore a thread’s box, or with –machine one of your machines, to one of its snapshots: everything on its disk since then goes, and the box restarts. BB Box takes an undo first, a snapshot of the box once stopped, unless –no-undo. It refuses while a person holds the box’s desktop or a BB terminal is open on it, unless –force. It refuses a box threads run on, as restores of such boxes stay off until BB Box can hold every turn on them. Asks for –replace.
bb box snapshot fork	Fork a snapshot of a thread’s box, or with –machine one of your machines, into a new box: of the box’s thread, or with –as-machine one of your machines. The fork gets the snapshot’s files, at its size, and an identity of its own: it resets at its first boot, and BB Box checks that before it is ready. Waits until it is ready. A kept snapshot of a box that was released forks, from its held copy on Proxmox and from the snapshot itself on Tart, as one of your machines; name its box as bb box snapshot list –all does.
bb box snapshot keep	Keep a snapshot of a thread’s box, or with –machine one of your machines, for 30 days from today unless Settings say otherwise, or until a date: it becomes yours, no agent can delete it, and it outlives its box’s release, as a held copy on Proxmox and as it is on Tart. BB Box deletes it after that date. Again on a kept snapshot, it renews its keep, never shortening it unless you give the date. A box that was released is named as bb box snapshot list –all names it.
bb box snapshot unkeep	Stop keeping a snapshot of a thread’s box, or with –machine one of your machines: it goes with its box again. A released box’s kept snapshot is deleted instead, with bb box snapshot delete.
bb box snapshot forget	Forget every snapshot BB Box records on a backend, so the backend can be removed from BB Box’s settings. BB Box deletes nothing: they may still exist there, and be billed. Asks for –yes.
bb box gpu update	Update NVIDIA’s userspace in a running box with a GPU to the host’s driver, after that driver changed (071). BB Box checks the box first: BB Box’s own Linux image on x86_64, 2 GiB free, and no NVIDIA or CUDA packages from apt. It then downloads NVIDIA’s installer for exactly the host’s driver, checks it against NVIDIA’s SHA-256, installs it with no kernel modules, restarts the box, and checks that nvidia-smi lists the box’s card and CUDA’s driver initialises, and for a desktop that it draws and encodes its video on the GPU. Everything running in the box stops. It is refused while a person holds control of the box’s desktop, and while threads are working on it unless –force. Several boxes are updated one at a time. BB Box never updates a box’s userspace by itself; bb box doctor names the boxes that need it.
bb box gpu mark	Mark each guest of this install whose device lines name a card with the claim they give, as a tag the host’s GPU helper answers (071): gpu.shared.<card’s UUID>.g<N>, or gpu.whole where the box’s record says a whole card, N above the last generation the helper answered for the guest. It changes only tags: it never restarts, stops or resizes a guest, never changes its device lines, and never touches a guest that is not this install’s; a running box is marked as it runs. It leaves, and names, a guest the helper would refuse or whose lines it would rewrite, one that is locked or has another marker, and checks each again from the config it reads just before it writes. It counts a guest granted only from the helper’s own answer to that marker. It waits up to 10 s for the answers, and exits 1 when it leaves a guest or the helper does not grant one. –undo clears each claim the helper holds for this install’s guests, through a gpu.release marker the helper answers, then takes that marker off: device lines stay as they are, and the helper no longer writes them.
bb box monitor snapshot	Show BB’s server’s CPU, load, memory, disk and processes, as the Monitor reads them. –json gives the whole reading, with its recent history.
bb box monitor health	Show the pressure on BB’s server. Exits 2 when it is critical; with –json it exits 0, and status says.
bb box monitor logs	Show background monitoring’s diagnostic records, oldest first: the last 100, or –limit up to 500. –json gives JSON lines.
bb box monitor test-alert	Show a labelled preview of a pressure alert in every BB window that is open and visible. Needs background monitoring and its notifications on.
bb box monitor history	Show box history (069): whether it reads boxes, how many readings were due, taken, skipped and failed each hour, each box’s newest point, and the room its file uses. –hours chooses how many hours, 24 by default.
bb box sweep	Run the clean-up now: release the boxes of ended threads, finish interrupted work and remove leftovers, and settle and check BB Box’s snapshots against each backend’s.

bb box doctor

Check each backend’s settings and host, and say how to fix what is wrong.

Usage:
  bb box doctor [--json]

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box kinds

List the kinds of box the active backends offer.

Usage:
  bb box kinds [--json]

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box list

List a thread’s boxes, or every box with –all.

Usage:
  bb box list [--thread <value>] [--json] [--all]

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --json            Print JSON.
  --all             List the boxes of every thread.
  --help, -h        Show this help and exit

bb box acquire

Acquire a box for a thread and wait until it answers.

Usage:
  bb box acquire <kind> [--thread <value>] [--json] [--size <small|medium|large>] [--cores <1-1024>] [--memory-gib <1-65536>] [--disk-gib <1-65536>] [--on <value>] [--image <value>] [--device <value>] [--no-slim] [--gpu <value>] [--dedicated] [--shared] [--no-wait]

Arguments:
  <kind>  The kind of box, from bb box kinds. (required)

Options:
  --thread <value>             The thread whose boxes to use. Defaults to the thread this runs in.
  --json                       Print JSON.
  --size <small|medium|large>  A preset. Defaults to the kind's default preset; bb box kinds shows each kind's sizes.
  --cores <1-1024>             Cores, for a custom size. Parts left out come from the preset.
  --memory-gib <1-65536>       Memory in GiB, for a custom size: at least 2 for a Linux box.
  --disk-gib <1-65536>         Root disk in GiB, for a custom size. Presets keep the kind's own disk.
  --on <value>                 The provider to use, from bb box kinds, such as "Docker on devpc", or several with commas between (pve1,devpc) for the first with room among them: only they are tried. Without it, the first with room.
  --image <value>              The image to start from: a project's image, from bb box image list, or "standard". The thread's project's image for the kind by default.
  --device <value>             For an ios or android box, the device it boots, such as iPhone 18 Pro or Pixel Fold. The kind's first by default.
  --no-slim                    For an ios box: its iOS Simulator keeps every service, for an app that uses widgets, Siri, iCloud, Health, Wallet or the like. Slimmed by default.
  --gpu <value>                The box's GPU: none, or shared, one card other boxes may share. Left out, the kind's GPU when not asked for: shared for linux-desktop and none for linux unless bb box kind set --gpu changed it.
  --dedicated                  For an ios box: a macOS VM of its own, with sudo, brew install, its own cores, ports and desktop. Without it, an ios box is shared where a shared iOS host has room. Give it with a size: where a shared iOS host is set up, a size without it is refused.
  --shared                     For an ios box: a macOS user on a Mac or VM shared with other ios boxes, ready in seconds, with its own device, files and keychain, but no sudo, Homebrew installs or app windows. For a macos box: a macOS user on a Mac or VM shared with ios boxes, ready in seconds, for commands, builds and the iOS Simulator, with its own files and keychain, but no sudo, Homebrew installs, desktop or app windows, and cores, ports and processes shared. Only where a shared iOS host is set up; box_list says.
  --no-wait                    Return once the box is recorded.
  --help, -h                   Show this help and exit

bb box status

Show one box, checking its power state with the backend.

Usage:
  bb box status <box> [--thread <value>] [--json]

Arguments:
  <box>  The box's name or ID. (required)

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --json            Print JSON.
  --help, -h        Show this help and exit

bb box run

Run a shell command in a thread’s box, or with –machine in one of your machines, as its user, and print its output. It exits with the command’s exit code. For a long command, use box_run, which keeps it as a job.

Usage:
  bb box run <box> <command...> [--thread <value>] [--machine] [--timeout-seconds <1-600>]

Arguments:
  <box>         The box's name or ID. (required)
  <command...>  The command, run by the box user's shell, such as "uname -a". Quote it as one word. (required)

Options:
  --thread <value>           The thread whose boxes to use. Defaults to the thread this runs in.
  --machine                  The box is one of your machines, from bb box machines, not a thread's.
  --timeout-seconds <1-600>  Seconds before the command is stopped: 120 by default, at most 600.
  --help, -h                 Show this help and exit

bb box resize

Resize a thread’s box: its cores, memory, disk or GPU, where its backend can, live or with –restart. Parts left out stay as they are, and the disk only grows.

Usage:
  bb box resize <box> [--thread <value>] [--size <small|medium|large>] [--cores <1-1024>] [--memory-gib <1-65536>] [--disk-gib <1-65536>] [--restart] [--check] [--force] [--gpu <value>]

Arguments:
  <box>  The box's name or ID. (required)

Options:
  --thread <value>             The thread whose boxes to use. Defaults to the thread this runs in.
  --size <small|medium|large>  A preset: its cores and memory. The disk stays as it is.
  --cores <1-1024>             Cores. Left out, the box keeps its own.
  --memory-gib <1-65536>       Memory in GiB: at least 2 for a Linux box. Left out, the box keeps its own.
  --disk-gib <1-65536>         Root disk in GiB, which only grows. Left out, the box keeps its own.
  --restart                    Allow a restart, which ends everything running in the box, where a part needs one.
  --check                      Only say what would change, how, and whether there is room.
  --force                      Restart it even while threads are working on it, which ends their work.
  --gpu <value>                The box's GPU: none, or shared, one card other boxes may share. Left out, the GPU stays as it is. On Proxmox LXC adding or removing a GPU needs --restart, and on Docker it cannot be done. A box with no NVIDIA userspace for the host's driver gets it installed in the same restart, about 60 s more, and a linux-desktop-cpu box becomes a GPU desktop, linux-desktop. A stopped box stays stopped. A resize whose plan changed since its --check is refused, saying what changed.
  --help, -h                   Show this help and exit

bb box machines

List your machines: boxes you own, kept as BB machines, which no thread ending releases.

Usage:
  bb box machines [--json]

Its commands:
  bb box machines add <kind>        Add a machine of your own, of the kind
  bb box machines resize <machine>  Resize one of your machines
  bb box machines remove <machine>  Remove one of your machines and delete its disk
Run one with --help for its options.

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box machines add

Add a machine of your own: a box of the kind, kept as a BB machine under the name until you remove it.

Usage:
  bb box machines add <kind> [--json] [--size <small|medium|large>] [--cores <1-1024>] [--memory-gib <1-65536>] [--disk-gib <1-65536>] [--on <value>] [--name <value>] [--no-wait]

Arguments:
  <kind>  The kind of box, from bb box kinds. It must be able to become a BB machine. (required)

Options:
  --json                       Print JSON.
  --size <small|medium|large>  A preset. Defaults to the kind's default preset; bb box kinds shows each kind's sizes.
  --cores <1-1024>             Cores, for a custom size. Parts left out come from the preset.
  --memory-gib <1-65536>       Memory in GiB, for a custom size: at least 2 for a Linux box.
  --disk-gib <1-65536>         Root disk in GiB, for a custom size. Presets keep the kind's own disk.
  --on <value>                 The provider to use, from bb box kinds, such as "Docker on devpc", or several with commas between (pve1,devpc) for the first with room among them: only they are tried. Without it, the first with room.
  --name <value>               Its name, which is also its BB machine's: a lower-case letter first, then letters, digits and "-". BB Box picks one when left out.
  --no-wait                    Return once the box is recorded.
  --help, -h                   Show this help and exit

bb box machines resize

Resize one of your machines: its cores, memory, disk or GPU, where its backend can, live or with –restart. Parts left out stay as they are, and the disk only grows.

Usage:
  bb box machines resize <machine> [--size <small|medium|large>] [--cores <1-1024>] [--memory-gib <1-65536>] [--disk-gib <1-65536>] [--restart] [--check] [--force] [--gpu <value>]

Arguments:
  <machine>  The machine's name or ID, from bb box machines. (required)

Options:
  --size <small|medium|large>  A preset: its cores and memory. The disk stays as it is.
  --cores <1-1024>             Cores. Left out, the box keeps its own.
  --memory-gib <1-65536>       Memory in GiB: at least 2 for a Linux box. Left out, the box keeps its own.
  --disk-gib <1-65536>         Root disk in GiB, which only grows. Left out, the box keeps its own.
  --restart                    Allow a restart, which ends everything running in the box, where a part needs one.
  --check                      Only say what would change, how, and whether there is room.
  --force                      Restart it even while threads are working on it, which ends their work.
  --gpu <value>                The box's GPU: none, or shared, one card other boxes may share. Left out, the GPU stays as it is. On Proxmox LXC adding or removing a GPU needs --restart, and on Docker it cannot be done. A box with no NVIDIA userspace for the host's driver gets it installed in the same restart, about 60 s more, and a linux-desktop-cpu box becomes a GPU desktop, linux-desktop. A stopped box stays stopped. A resize whose plan changed since its --check is refused, saying what changed.
  --help, -h                   Show this help and exit

bb box machines remove

Remove one of your machines: its box is released and its disk deleted. A machine a thread is working on is refused unless –force. Snapshots you kept are copied first, so they outlive it, unless –delete-kept.

Usage:
  bb box machines remove <machine> [--force] [--delete-kept]

Arguments:
  <machine>  The machine's name or ID, from bb box machines. (required)

Options:
  --force        Remove it even while threads are working on it, which ends their work.
  --delete-kept  Delete the snapshots of it you kept too, instead of copying them first so they outlive it.
  --help, -h     Show this help and exit

bb box thread

Start a child thread of a thread on one of its boxes, as a BB machine, with the thread’s project.

Usage:
  bb box thread <box> [--thread <value>] [--json] --prompt <value>

Arguments:
  <box>  The box's name or ID. (required)

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --json            Print JSON.
  --prompt <value>  The child thread's first message. (required)
  --help, -h        Show this help and exit

bb box release

Release a box. Its disk is deleted. A box a thread is working on is refused unless –force. Snapshots you kept are copied first, so they outlive it, unless –delete-kept.

Usage:
  bb box release <box> [--thread <value>] [--force] [--delete-kept]

Arguments:
  <box>  The box's name or ID. (required)

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --force           Release it even while threads are working on it, which ends their work.
  --delete-kept     Delete the snapshots of it you kept too, instead of copying them first so they outlive it.
  --help, -h        Show this help and exit

bb box stop

Stop a thread’s box, or with –machine one of your machines, keeping its disk. A box a thread is working on is refused unless –force.

Usage:
  bb box stop <box> [--thread <value>] [--machine] [--force]

Arguments:
  <box>  The box's name or ID. (required)

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --machine         The box is one of your machines, from bb box machines, not a thread's.
  --force           Stop it even while threads are working on it, which ends their work.
  --help, -h        Show this help and exit

bb box start

Start a thread’s stopped box, or with –machine one of your machines, and wait until it answers.

Usage:
  bb box start <box> [--thread <value>] [--machine] [--json]

Arguments:
  <box>  The box's name or ID. (required)

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --machine         The box is one of your machines, from bb box machines, not a thread's.
  --json            Print JSON.
  --help, -h        Show this help and exit

bb box enrol

Add a ready box that is not a BB machine to BB again, as a thread’s box, or with –machine one of your machines: BB’s installer runs in it as its user. It does not restart, stop or resize the box. It stops only the BB daemon of a machine that BB no longer has. A box whose machine BB still has is left as it is, and recorded as a BB machine. Waits up to 2 minutes for the try.

Usage:
  bb box enrol <box> [--thread <value>] [--machine] [--json]

Arguments:
  <box>  The box's name or ID. (required)

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --machine         The box is one of your machines, from bb box machines, not a thread's.
  --json            Print JSON.
  --help, -h        Show this help and exit

bb box forget

Forget a box whose backend is no longer in BB Box’s settings: BB Box removes its record and deletes nothing, so a guest that still runs keeps running.

Usage:
  bb box forget <box> [--thread <value>] [--machine]

Arguments:
  <box>  The box's name or ID. (required)

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --machine         The box is one of your machines, from bb box machines, not a thread's.
  --help, -h        Show this help and exit

bb box image set

Set a project’s image (049): a script run as root on its kinds’ standard images, for the boxes of the project’s threads, with an optional check run as the box user. BB Box keeps a copy of the files. Setting it changes every new box of those kinds in the project.

Usage:
  bb box image set <name> [--kinds <value>] [--script-file <value>] [--check-file <value>] [--project <value>] [--bake <value>]

Arguments:
  <name>  The image's name: a lower-case letter first, then letters, digits and "-". (required)

Options:
  --kinds <value>        The kinds it builds on, comma-separated, such as linux,linux-desktop-cpu.
  --script-file <value>  The script, such as .bb/box-setup.sh, read where bb runs.
  --check-file <value>   A check run as the box user after the script, such as .bb/box-check.sh.
  --project <value>      The BB projects whose boxes get it, by ID, comma-separated.
  --bake <value>         auto (after two boxes in 14 days), always, or never (the script at each start). auto by default.
  --help, -h             Show this help and exit

bb box image remove

Remove a project’s image (049). Boxes of its kinds in its projects start from the standard images again.

Usage:
  bb box image remove <name>

Arguments:
  <name>  The image's name, from bb box image list. (required)

bb box image list

List projects’ images (049): each one’s kinds, projects, how it is baked, where its script came from, and its builds.

Usage:
  bb box image list [--json]

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box image show

Print a project’s image’s script, and its check, as BB Box keeps them (049).

Usage:
  bb box image show <name>

Arguments:
  <name>  The image's name, from bb box image list. (required)

bb box image try

Try a project’s image’s script as a build runs it (049), on a kind it covers, and remove what the try made. It prints each check’s result and the build’s last lines, and exits 1 if one failed.

Usage:
  bb box image try <name> [--kind <value>] [--on <value>]

Arguments:
  <name>  The image's name, from bb box image list. (required)

Options:
  --kind <value>  The kind to try it on: its first kind by default.
  --on <value>    A backend's ID, such as proxmox-lxc: the first that builds the kind's images by default.
  --help, -h      Show this help and exit

bb box images list

List the standard images BB Box rebuilds (049): each one’s build and age, why it is due, and what its last rebuild did, most needed first.

Usage:
  bb box images list [--json] [--output <value>]

Options:
  --json            Print JSON.
  --output <value>  Print this image's last rebuild's last lines, as <backend>/<ref>.
  --help, -h        Show this help and exit

bb box images refresh

Rebuild the standard images that are due (049), one at a time, most needed first, and start none after the time limit. A BB script automation runs it each night. It ends with a line per image, and exits 1 if one failed. Should this command end first, the run goes on.

Usage:
  bb box images refresh [--pinned] [--hours <value>]

Options:
  --pinned         Build from the repository's pins alone.
  --hours <value>  Start no image after this many hours: 4 by default.
  --help, -h       Show this help and exit

bb box images build

Rebuild one standard image now, due or not, and whatever its last rebuild did (049), and replace it when its trial box passes. –try checks a new build and keeps the old one.

Usage:
  bb box images build <image> [--pinned] [--try]

Arguments:
  <image>  The image, as <backend>/<ref>, from bb box images list. (required)

Options:
  --pinned    Build from the repository's pins alone.
  --try       Build and check, then keep the old build.
  --help, -h  Show this help and exit

bb box images versions

Show what a rebuild of the standard Linux images would take now (049): upstream’s latest stable Claude Code, Codex, pi, gh and Chrome, each with the SHA-256 it publishes, and the day’s apt snapshot, against this BB Box’s pins.

Usage:
  bb box images versions [--json] [--pinned]

Options:
  --json      Print JSON.
  --pinned    Take the repository's pins alone, as a build with --pinned does.
  --help, -h  Show this help and exit

bb box setup docker

Set up Docker for boxes, as the Box panel’s first run does: on the BB machine that runs BB, or –machine, turn Docker on with the Linux image alone and wait while it builds, usually 5 to 12 min. Where something stands in the way, it gives that machine’s line to fix it. –no-wait starts it and says how far the build is; run it again to see.

Usage:
  bb box setup docker [--machine <value>] [--no-wait] [--set-machine-access]

Options:
  --machine <value>     The BB machine, by ID or name, from bb machine list. The one that runs BB by default.
  --no-wait             Start the build, and say how far it is, without waiting for it.
  --set-machine-access  Where BB listens on every address and boxes cannot join, set Machine access to direct at an address they can reach. This changes BB's settings. Without it, the command only says it can.
  --help, -h            Show this help and exit

bb box docker-check

Check that Docker on a BB machine answers through BB Box’s Docker relay (042), with its version, cores and memory.

Usage:
  bb box docker-check <machine> [--json]

Arguments:
  <machine>  The BB machine's ID or name, from bb machine list. (required)

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box docker-build

Build the images a BB machine that hosts Docker boxes lacks there, or has from another layout or with another build of BB’s app, through BB Box’s relay (042). Waits for the build. Building all three needs about 36 GB free there; with less, it does not start.

Usage:
  bb box docker-build <machine>

Arguments:
  <machine>  The BB machine's ID or name, from bb machine list. Its Docker must be added in BB Box's settings, under Add backend. (required)

bb box install-id

Show this install’s ID, which it records on its guests. –set takes back the ID it had before it lost its storage.

Usage:
  bb box install-id [--json] [--set <value>]

Options:
  --json         Print JSON.
  --set <value>  The ID to use from now on, as bb box doctor lists it.
  --help, -h     Show this help and exit

bb box config show

Show BB Box’s configuration. –json prints it as a file for config apply, with no secret in it: keep it to set BB Box up again.

Usage:
  bb box config show [--json]

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box config check

Check a configuration file without saving it. –test also runs the doctor of each backend in it that is on, within 30 s each.

Usage:
  bb box config check <file> [--json] [--test]

Arguments:
  <file>  A JSON file in the form bb box config show --json prints. It is read on the machine BB's server runs on; a relative path is from where you run bb. (required)

Options:
  --json      Print JSON.
  --test      Run each backend's doctor against the file's settings. It acquires nothing.
  --help, -h  Show this help and exit

bb box config apply

Save a configuration file as BB Box’s whole configuration, then rebuild what changed. A revision in the file must be the current one; a file without one, or –replace, saves over what is there, as when setting BB Box up again from an export.

Usage:
  bb box config apply <file> [--json] [--replace]

Arguments:
  <file>  A JSON file in the form bb box config show --json prints. It is read on the machine BB's server runs on; a relative path is from where you run bb. (required)

Options:
  --json      Print JSON.
  --replace   Save over the current configuration whatever revision the file names.
  --help, -h  Show this help and exit

bb box config migrated

Show the copy of BB’s settings BB Box kept when it moved them into its configuration. –remove removes it.

Usage:
  bb box config migrated [--json] [--remove]

Options:
  --json      Print JSON.
  --remove    Remove the copy.
  --help, -h  Show this help and exit

bb box backend list

List the configuration’s backends, in the order a new box tries them: each one’s switch, state, kinds, boxes and last check.

Usage:
  bb box backend list [--json]

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box backend types

List the types of backend BB Box has: what each is for, what setting it up needs, the kinds it makes, and its setup guide and scripts in BB Box’s repository.

Usage:
  bb box backend types [--json]

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box backend fields

List a backend type’s fields, or a backend’s with their values now: each key, what it takes, whether it is a secret, and the first line of its help. Secrets show only as set or not.

Usage:
  bb box backend fields <backend> [--json]

Arguments:
  <backend>  A type, from bb box backend types, or a backend's ID, from bb box backend list. (required)

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box backend add

Add a backend, on unless –off, through the same checked save as the settings page, then run its checks. Secrets come only from a dotenv file or stdin. Exits 2 when it saved and its checks failed.

Usage:
  bb box backend add <type> [--json] [--check] [--revision <n>] [--operation <value>] [--field <key=value>]... [--field-file <key=path>]... [--unset <key>]... [--add-line <key=line>]... [--remove-line <key=text>]... [--secret-file <field=path>]... [--clear-secret <field>]... [--secret <field=VARIABLE>]... [--secrets-file <path>] [--secrets <line>] [--on] [--off] [--label <value>] [--warm <kind=count>]... [--no-doctor] [--id <value>]

Arguments:
  <type>  The type, from bb box backend types, such as docker or ssh-pool. (required)

Options:
  --json                      Print JSON.
  --check                     Save nothing: say what would change and what is wrong with it, and for a backend run its checks with the change, as the settings page's Check does.
  --revision <n>              Save only while the configuration is at this revision, which bb box config show gives, and refuse otherwise. Left out, the change is made on the latest revision, trying up to 3 times.
  --operation <value>         An ID for this save. The same command again with the same ID, as after an answer that never came, is saved once and answers with the first save's receipt, kept 24 hours. A new ID is made when left out.
  --field <key=value>         Set a field, such as host=unix:///var/run/docker.sock. Repeat for each. key= with nothing after it saves an empty value, which for an image or template field turns its kind off here. Not for secrets. (repeatable)
  --field-file <key=path>     Set a field to a file's text, for a field of several lines, such as known-hosts. Read on the machine BB's server runs on. (repeatable)
  --unset <key>               Leave a field unset, so it takes its default. (repeatable)
  --add-line <key=line>       Add a line to a field of lines, such as machines="build-1 192.0.2.21 linux". A line already there is not added again. (repeatable)
  --remove-line <key=text>    Remove the lines of a field that are the text or start with it and a space, such as machines=build-1. (repeatable)
  --secret-file <field=path>  Set a secret field to a whole file's text, such as ssh-private-key=key.pem. Read on the machine BB's server runs on. (repeatable)
  --clear-secret <field>      Clear a secret field. (repeatable)
  --secret <field=VARIABLE>   A secret field and the variable in the dotenv file that holds its value, such as token=HCLOUD_TOKEN. Repeat for each. The value is read from --secrets-file or --secrets-stdin, never from the command line. (repeatable)
  --secrets-file <path>       A dotenv file, as bb secret request --write-env writes, read on the machine BB's server runs on; a relative path is from where you run bb.
  --secrets <line>            Only as --secrets-stdin, which reads one line: a VARIABLE=value line, as grep '^HCLOUD_TOKEN=' secrets.env | bb box backend add hetzner --secret token=HCLOUD_TOKEN --secrets-stdin, or a whole dotenv file in base64, as base64 < secrets.env | tr -d '\n' | bb box ... --secrets-stdin, for several secrets at once. Works from any machine. (or --secrets-stdin from the bb CLI)
  --on                        Turn it on.
  --off                       Turn it off: it makes no new boxes, and its boxes keep working.
  --label <value>             Its name in the settings and in box_list, such as Docker on build-1. Empty gives back the type's name.
  --warm <kind=count>         Ready boxes of a kind to keep waiting here, such as linux=1; 0 keeps none. (repeatable)
  --no-doctor                 Do not run the backend's checks after saving.
  --id <value>                Its ID, for a second backend of a type that allows several, such as docker:build-1, or just build-1. The type by default.
  --help, -h                  Show this help and exit

bb box backend set

Change a backend: its fields, secrets, switch, name or warm boxes, through the same checked save as the settings page, then run its checks. Exits 2 when it saved and its checks failed.

Usage:
  bb box backend set <backend> [--json] [--check] [--revision <n>] [--operation <value>] [--field <key=value>]... [--field-file <key=path>]... [--unset <key>]... [--add-line <key=line>]... [--remove-line <key=text>]... [--secret-file <field=path>]... [--clear-secret <field>]... [--secret <field=VARIABLE>]... [--secrets-file <path>] [--secrets <line>] [--on] [--off] [--label <value>] [--warm <kind=count>]... [--no-doctor]

Arguments:
  <backend>  The backend's ID, from bb box backend list. (required)

Options:
  --json                      Print JSON.
  --check                     Save nothing: say what would change and what is wrong with it, and for a backend run its checks with the change, as the settings page's Check does.
  --revision <n>              Save only while the configuration is at this revision, which bb box config show gives, and refuse otherwise. Left out, the change is made on the latest revision, trying up to 3 times.
  --operation <value>         An ID for this save. The same command again with the same ID, as after an answer that never came, is saved once and answers with the first save's receipt, kept 24 hours. A new ID is made when left out.
  --field <key=value>         Set a field, such as host=unix:///var/run/docker.sock. Repeat for each. key= with nothing after it saves an empty value, which for an image or template field turns its kind off here. Not for secrets. (repeatable)
  --field-file <key=path>     Set a field to a file's text, for a field of several lines, such as known-hosts. Read on the machine BB's server runs on. (repeatable)
  --unset <key>               Leave a field unset, so it takes its default. (repeatable)
  --add-line <key=line>       Add a line to a field of lines, such as machines="build-1 192.0.2.21 linux". A line already there is not added again. (repeatable)
  --remove-line <key=text>    Remove the lines of a field that are the text or start with it and a space, such as machines=build-1. (repeatable)
  --secret-file <field=path>  Set a secret field to a whole file's text, such as ssh-private-key=key.pem. Read on the machine BB's server runs on. (repeatable)
  --clear-secret <field>      Clear a secret field. (repeatable)
  --secret <field=VARIABLE>   A secret field and the variable in the dotenv file that holds its value, such as token=HCLOUD_TOKEN. Repeat for each. The value is read from --secrets-file or --secrets-stdin, never from the command line. (repeatable)
  --secrets-file <path>       A dotenv file, as bb secret request --write-env writes, read on the machine BB's server runs on; a relative path is from where you run bb.
  --secrets <line>            Only as --secrets-stdin, which reads one line: a VARIABLE=value line, as grep '^HCLOUD_TOKEN=' secrets.env | bb box backend add hetzner --secret token=HCLOUD_TOKEN --secrets-stdin, or a whole dotenv file in base64, as base64 < secrets.env | tr -d '\n' | bb box ... --secrets-stdin, for several secrets at once. Works from any machine. (or --secrets-stdin from the bb CLI)
  --on                        Turn it on.
  --off                       Turn it off: it makes no new boxes, and its boxes keep working.
  --label <value>             Its name in the settings and in box_list, such as Docker on build-1. Empty gives back the type's name.
  --warm <kind=count>         Ready boxes of a kind to keep waiting here, such as linux=1; 0 keeps none. (repeatable)
  --no-doctor                 Do not run the backend's checks after saving.
  --help, -h                  Show this help and exit

bb box backend remove

Remove a backend: its settings, its secrets, which cannot be got back, and its warm boxes. Refused while it has boxes, as on the settings page. Asks for –yes.

Usage:
  bb box backend remove <backend> [--json] [--check] [--revision <n>] [--operation <value>] [--yes]

Arguments:
  <backend>  The backend's ID, from bb box backend list. (required)

Options:
  --json               Print JSON.
  --check              Save nothing: say what would change and what is wrong with it, and for a backend run its checks with the change, as the settings page's Check does.
  --revision <n>       Save only while the configuration is at this revision, which bb box config show gives, and refuse otherwise. Left out, the change is made on the latest revision, trying up to 3 times.
  --operation <value>  An ID for this save. The same command again with the same ID, as after an answer that never came, is saved once and answers with the first save's receipt, kept 24 hours. A new ID is made when left out.
  --yes                Remove it. Without it, the command says what would go and removes nothing.
  --help, -h           Show this help and exit

bb box backend host add

Add a host to a backend whose hosts are set up alike, such as a Mac to Tart. The SSH host pool lists its machines in its machines field instead: bb box backend set ssh-pool –add-line.

Usage:
  bb box backend host add <backend> <host> [--json] [--check] [--revision <n>] [--operation <value>] [--field <key=value>]... [--field-file <key=path>]... [--unset <key>]... [--on] [--off] [--no-doctor]

Arguments:
  <backend>  The backend's ID, such as tart. (required)
  <host>     The host's name: lower-case letters, digits and "-", such as mac-1. (required)

Options:
  --json                   Print JSON.
  --check                  Save nothing: say what would change and what is wrong with it, and for a backend run its checks with the change, as the settings page's Check does.
  --revision <n>           Save only while the configuration is at this revision, which bb box config show gives, and refuse otherwise. Left out, the change is made on the latest revision, trying up to 3 times.
  --operation <value>      An ID for this save. The same command again with the same ID, as after an answer that never came, is saved once and answers with the first save's receipt, kept 24 hours. A new ID is made when left out.
  --field <key=value>      Set a field, such as host=unix:///var/run/docker.sock. Repeat for each. key= with nothing after it saves an empty value, which for an image or template field turns its kind off here. Not for secrets. (repeatable)
  --field-file <key=path>  Set a field to a file's text, for a field of several lines, such as known-hosts. Read on the machine BB's server runs on. (repeatable)
  --unset <key>            Leave a field unset, so it takes its default. (repeatable)
  --on                     Turn it on.
  --off                    Turn it off: it makes no new boxes, and its boxes keep working.
  --no-doctor              Do not run the backend's checks after saving.
  --help, -h               Show this help and exit

bb box backend host set

Change a backend’s host: its fields, or its switch. Off, it takes no new boxes, and its boxes keep working.

Usage:
  bb box backend host set <backend> <host> [--json] [--check] [--revision <n>] [--operation <value>] [--field <key=value>]... [--field-file <key=path>]... [--unset <key>]... [--on] [--off] [--no-doctor]

Arguments:
  <backend>  The backend's ID, such as tart. (required)
  <host>     The host's name, from bb box backend list. (required)

Options:
  --json                   Print JSON.
  --check                  Save nothing: say what would change and what is wrong with it, and for a backend run its checks with the change, as the settings page's Check does.
  --revision <n>           Save only while the configuration is at this revision, which bb box config show gives, and refuse otherwise. Left out, the change is made on the latest revision, trying up to 3 times.
  --operation <value>      An ID for this save. The same command again with the same ID, as after an answer that never came, is saved once and answers with the first save's receipt, kept 24 hours. A new ID is made when left out.
  --field <key=value>      Set a field, such as host=unix:///var/run/docker.sock. Repeat for each. key= with nothing after it saves an empty value, which for an image or template field turns its kind off here. Not for secrets. (repeatable)
  --field-file <key=path>  Set a field to a file's text, for a field of several lines, such as known-hosts. Read on the machine BB's server runs on. (repeatable)
  --unset <key>            Leave a field unset, so it takes its default. (repeatable)
  --on                     Turn it on.
  --off                    Turn it off: it makes no new boxes, and its boxes keep working.
  --no-doctor              Do not run the backend's checks after saving.
  --help, -h               Show this help and exit

bb box backend host remove

Remove a host from a backend. Refused while it has boxes, as on the settings page.

Usage:
  bb box backend host remove <backend> <host> [--json] [--check] [--revision <n>] [--operation <value>]

Arguments:
  <backend>  The backend's ID, such as tart. (required)
  <host>     The host's name, from bb box backend list. (required)

Options:
  --json               Print JSON.
  --check              Save nothing: say what would change and what is wrong with it, and for a backend run its checks with the change, as the settings page's Check does.
  --revision <n>       Save only while the configuration is at this revision, which bb box config show gives, and refuse otherwise. Left out, the change is made on the latest revision, trying up to 3 times.
  --operation <value>  An ID for this save. The same command again with the same ID, as after an answer that never came, is saved once and answers with the first save's receipt, kept 24 hours. A new ID is made when left out.
  --help, -h           Show this help and exit

bb box kind set

Change a kind: whether it is offered, its presets’ sizes, its default preset, its largest custom size, its spare boxes, its GPU when not asked for, or make it the default kind, through the same checked save as the settings page. Sizes and the GPU change new boxes only.

Usage:
  bb box kind set <kind> [--json] [--check] [--revision <n>] [--operation <value>] [--on] [--off] [--make-default] [--default-preset <small|medium|large>] [--preset <small|medium|large>] [--cores <1-1024>] [--memory-gib <value>] [--disk-gib <value>] [--largest-cores <1-1024>] [--largest-memory-gib <value>] [--largest-disk-gib <value>] [--spares <0-100>] [--gpu <none|shared|whole>] [--reset]

Arguments:
  <kind>  The kind, such as linux. bb box kinds lists those on offer. (required)

Options:
  --json                         Print JSON.
  --check                        Save nothing: say what would change and what is wrong with it, and for a backend run its checks with the change, as the settings page's Check does.
  --revision <n>                 Save only while the configuration is at this revision, which bb box config show gives, and refuse otherwise. Left out, the change is made on the latest revision, trying up to 3 times.
  --operation <value>            An ID for this save. The same command again with the same ID, as after an answer that never came, is saved once and answers with the first save's receipt, kept 24 hours. A new ID is made when left out.
  --on                           Turn it on.
  --off                          Turn it off: it makes no new boxes, and its boxes keep working.
  --make-default                 Make it the kind a thread gets when it asks for none.
  --default-preset <small|medium|large>  The preset a box gets when it asks for no size.
  --preset <small|medium|large>  The preset that --cores, --memory-gib and --disk-gib change. The kind's default preset by default.
  --cores <1-1024>               The preset's cores.
  --memory-gib <value>           The preset's memory in GiB, such as 8 or 0.5.
  --disk-gib <value>             The preset's disk in GiB, or "base" for the size the image comes with.
  --largest-cores <1-1024>       The most cores a custom size may ask for.
  --largest-memory-gib <value>   The most memory in GiB a custom size may ask for.
  --largest-disk-gib <value>     The most disk in GiB a custom size may ask for.
  --spares <0-100>               Spare boxes to keep ready, enrolled and owned by no thread; 0 keeps none.
  --gpu <none|shared|whole>      The GPU a box of the kind gets when a request leaves gpu out, and the New box form's first choice: none, shared or whole. linux and linux-desktop only.
  --reset                        Go back to BB Box's own sizes and switch for the kind first.
  --help, -h                     Show this help and exit

bb box option list

List the general and Monitor options: each one’s value now, its default, and what it does.

Usage:
  bb box option list [--json]

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box option get

Show one general or Monitor option: its value now, its default, and what it does.

Usage:
  bb box option get <option> [--json]

Arguments:
  <option>  The option's name, such as monitor.enabled or defaultKind. (required)

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box option set

Set general and Monitor options, such as monitor.enabled=false, defaultKind=linux or general.snapshots.ceilings.=7.50, a ceiling on a backend’s paid snapshots, in one checked save, as the settings page saves them. bb box option list lists them.

Usage:
  bb box option set [<options...>] [--json] [--check] [--revision <n>] [--operation <value>] [--secret <field=VARIABLE>]... [--secrets-file <path>] [--secrets <line>]

Arguments:
  <options...>  Each as <name>=<value>, such as monitor.enabled=false; or one name and its value as two words.

Options:
  --json                     Print JSON.
  --check                    Save nothing: say what would change and what is wrong with it, and for a backend run its checks with the change, as the settings page's Check does.
  --revision <n>             Save only while the configuration is at this revision, which bb box config show gives, and refuse otherwise. Left out, the change is made on the latest revision, trying up to 3 times.
  --operation <value>        An ID for this save. The same command again with the same ID, as after an answer that never came, is saved once and answers with the first save's receipt, kept 24 hours. A new ID is made when left out.
  --secret <field=VARIABLE>  A secret field and the variable in the dotenv file that holds its value, such as token=HCLOUD_TOKEN. Repeat for each. The value is read from --secrets-file or --secrets-stdin, never from the command line. (repeatable)
  --secrets-file <path>      A dotenv file, as bb secret request --write-env writes, read on the machine BB's server runs on; a relative path is from where you run bb.
  --secrets <line>           Only as --secrets-stdin, which reads one line: a VARIABLE=value line, as grep '^HCLOUD_TOKEN=' secrets.env | bb box backend add hetzner --secret token=HCLOUD_TOKEN --secrets-stdin, or a whole dotenv file in base64, as base64 < secrets.env | tr -d '\n' | bb box ... --secrets-stdin, for several secrets at once. Works from any machine. (or --secrets-stdin from the bb CLI)
  --help, -h                 Show this help and exit

bb box option unset

Give general and Monitor options back their defaults, in one checked save. general.tailnet.mode turns the tailnet off and clears its client.

Usage:
  bb box option unset <options...> [--json] [--check] [--revision <n>] [--operation <value>]

Arguments:
  <options...>  The options' names, such as monitor.refreshIntervalSeconds. (required)

Options:
  --json               Print JSON.
  --check              Save nothing: say what would change and what is wrong with it, and for a backend run its checks with the change, as the settings page's Check does.
  --revision <n>       Save only while the configuration is at this revision, which bb box config show gives, and refuse otherwise. Left out, the change is made on the latest revision, trying up to 3 times.
  --operation <value>  An ID for this save. The same command again with the same ID, as after an answer that never came, is saved once and answers with the first save's receipt, kept 24 hours. A new ID is made when left out.
  --help, -h           Show this help and exit

bb box snapshot take

Take a snapshot of a thread’s box, or with –machine one of your machines: its disk, or with –memory its disk and its memory where its backend can. Waits until the backend confirms it. A box holds as many as Settings, Snapshots allows, 5 unless set.

Usage:
  bb box snapshot take <box> [--thread <value>] [--machine] [--json] [--name <value>] [--note <value>] [--memory] [--no-memory] [--request <value>]

Arguments:
  <box>  The box's name or ID. (required)

Options:
  --thread <value>   The thread whose boxes to use. Defaults to the thread this runs in.
  --machine          The box is one of your machines, from bb box machines, not a thread's.
  --json             Print JSON.
  --name <value>     Its name, at most 60 characters, unique on the box. The time, such as Thu 10:42, when left out.
  --note <value>     A note, at most 1 KB.
  --memory           Hold the box's memory too, so a restore brings back its running apps: only where its backend can, and slower. Where every snapshot holds it, as on a macOS box on Tart, a take holds it unasked.
  --no-memory        Hold the box's disk only. Refused where every snapshot holds the memory.
  --request <value>  An ID you make, so a repeat of this command is the same take.
  --help, -h         Show this help and exit

bb box snapshot list

List the snapshots of a box, of a thread’s boxes, of your machines with –machine, or with –all every snapshot BB Box records, those of released boxes too.

Usage:
  bb box snapshot list [<box>] [--thread <value>] [--machine] [--json] [--all] [--kept]

Arguments:
  <box>  The box's name or ID. Every box of the thread, or of your machines, when left out.

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --machine         The box is one of your machines, from bb box machines, not a thread's.
  --json            Print JSON.
  --all             Every snapshot BB Box records, of every thread's boxes and of boxes that are gone.
  --kept            Only kept snapshots.
  --help, -h        Show this help and exit

bb box snapshot delete

Delete a snapshot of a thread’s box, or with –machine one of your machines, by its name or ID, and wait until its backend confirms. An incomplete one is cleaned up on its host. A box that is gone is named by the ID bb box snapshot list –all gives.

Usage:
  bb box snapshot delete <box> <snapshot> [--thread <value>] [--machine] [--json] [--request <value>]

Arguments:
  <box>       The box's name or ID. (required)
  <snapshot>  The snapshot's name or ID. (required)

Options:
  --thread <value>   The thread whose boxes to use. Defaults to the thread this runs in.
  --machine          The box is one of your machines, from bb box machines, not a thread's.
  --json             Print JSON.
  --request <value>  An ID you make, so a repeat of this command is the same delete.
  --help, -h         Show this help and exit

bb box snapshot restore

Restore a thread’s box, or with –machine one of your machines, to one of its snapshots: everything on its disk since then goes, and the box restarts. BB Box takes an undo first, a snapshot of the box once stopped, unless –no-undo. It refuses while a person holds the box’s desktop or a BB terminal is open on it, unless –force. It refuses a box threads run on, as restores of such boxes stay off until BB Box can hold every turn on them. Asks for –replace.

Usage:
  bb box snapshot restore <box> <snapshot> [--thread <value>] [--machine] [--json] [--replace] [--no-undo] [--force] [--unflushed] [--check] [--request <value>]

Arguments:
  <box>       The box's name or ID. (required)
  <snapshot>  The snapshot's name or ID. (required)

Options:
  --thread <value>   The thread whose boxes to use. Defaults to the thread this runs in.
  --machine          The box is one of your machines, from bb box machines, not a thread's.
  --json             Print JSON.
  --replace          Replace the box's disk with the snapshot's.
  --no-undo          Take no undo first, so this cannot be undone.
  --force            Restore anyway while a person holds the box's desktop or a BB terminal is open on it, ending them.
  --unflushed        Restore anyway when BB Box cannot flush the box's writes to its disk before stopping it, so its undo may miss the last seconds' writes.
  --check            Say what the restore would do, and refuse what it would refuse, changing nothing.
  --request <value>  An ID you make, so a repeat of this command is the same restore.
  --help, -h         Show this help and exit

bb box snapshot fork

Fork a snapshot of a thread’s box, or with –machine one of your machines, into a new box: of the box’s thread, or with –as-machine one of your machines. The fork gets the snapshot’s files, at its size, and an identity of its own: it resets at its first boot, and BB Box checks that before it is ready. Waits until it is ready. A kept snapshot of a box that was released forks, from its held copy on Proxmox and from the snapshot itself on Tart, as one of your machines; name its box as bb box snapshot list –all does.

Usage:
  bb box snapshot fork <box> <snapshot> [--thread <value>] [--machine] [--json] [--as-machine] [--name <value>] [--check] [--request <value>] [--gpu <value>]

Arguments:
  <box>       The box's name or ID. (required)
  <snapshot>  The snapshot's name or ID. (required)

Options:
  --thread <value>   The thread whose boxes to use. Defaults to the thread this runs in.
  --machine          The box is one of your machines, from bb box machines, not a thread's.
  --json             Print JSON.
  --as-machine       Make the fork one of your machines, not a box of the source's thread.
  --name <value>     The new box's name. One is made up when left out.
  --check            Say what the fork would be, and refuse what it would refuse, changing nothing.
  --request <value>  An ID you make, so a repeat of this command is the same fork.
  --gpu <value>      none, the default, or shared. A shared fork places a card before the copy, and only a desktop can take it.
  --help, -h         Show this help and exit

bb box snapshot keep

Keep a snapshot of a thread’s box, or with –machine one of your machines, for 30 days from today unless Settings say otherwise, or until a date: it becomes yours, no agent can delete it, and it outlives its box’s release, as a held copy on Proxmox and as it is on Tart. BB Box deletes it after that date. Again on a kept snapshot, it renews its keep, never shortening it unless you give the date. A box that was released is named as bb box snapshot list –all names it.

Usage:
  bb box snapshot keep <box> <snapshot> [--thread <value>] [--machine] [--json] [--days <1-365>] [--until <value>] [--check]

Arguments:
  <box>       The box's name or ID. (required)
  <snapshot>  The snapshot's name or ID. (required)

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --machine         The box is one of your machines, from bb box machines, not a thread's.
  --json            Print JSON.
  --days <1-365>    Keep it this many days from today.
  --until <value>   Keep it until the end of this day, in UTC, as yyyy-mm-dd.
  --check           Say what keeping it would cost and refuse what it would refuse, changing nothing.
  --help, -h        Show this help and exit

bb box snapshot unkeep

Stop keeping a snapshot of a thread’s box, or with –machine one of your machines: it goes with its box again. A released box’s kept snapshot is deleted instead, with bb box snapshot delete.

Usage:
  bb box snapshot unkeep <box> <snapshot> [--thread <value>] [--machine] [--json]

Arguments:
  <box>       The box's name or ID. (required)
  <snapshot>  The snapshot's name or ID. (required)

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --machine         The box is one of your machines, from bb box machines, not a thread's.
  --json            Print JSON.
  --help, -h        Show this help and exit

bb box snapshot forget

Forget every snapshot BB Box records on a backend, so the backend can be removed from BB Box’s settings. BB Box deletes nothing: they may still exist there, and be billed. Asks for –yes.

Usage:
  bb box snapshot forget <backend> [--yes]

Arguments:
  <backend>  The backend's ID, from bb box backend list. (required)

Options:
  --yes       Forget them.
  --help, -h  Show this help and exit

bb box gpu update

Update NVIDIA’s userspace in a running box with a GPU to the host’s driver, after that driver changed (071). BB Box checks the box first: BB Box’s own Linux image on x86_64, 2 GiB free, and no NVIDIA or CUDA packages from apt. It then downloads NVIDIA’s installer for exactly the host’s driver, checks it against NVIDIA’s SHA-256, installs it with no kernel modules, restarts the box, and checks that nvidia-smi lists the box’s card and CUDA’s driver initialises, and for a desktop that it draws and encodes its video on the GPU. Everything running in the box stops. It is refused while a person holds control of the box’s desktop, and while threads are working on it unless –force. Several boxes are updated one at a time. BB Box never updates a box’s userspace by itself; bb box doctor names the boxes that need it.

Usage:
  bb box gpu update <box...> [--thread <value>] [--machine] [--check] [--force] [--snapshot] [--json]

Arguments:
  <box...>  The box's name or ID. Several, with spaces between, are updated one at a time. (required)

Options:
  --thread <value>  The thread whose boxes to use. Defaults to the thread this runs in.
  --machine         The boxes are your machines, from bb box machines, not a thread's.
  --check           Only say what it would do, and what stops; it changes nothing.
  --force           Restart it even while threads are working on it, which ends their work.
  --snapshot        Take a snapshot of the box first, where its provider takes snapshots, so it can be restored.
  --json            Print JSON.
  --help, -h        Show this help and exit

bb box gpu mark

Mark each guest of this install whose device lines name a card with the claim they give, as a tag the host’s GPU helper answers (071): gpu.shared.<card’s UUID>.g, or gpu.whole where the box’s record says a whole card, N above the last generation the helper answered for the guest. It changes only tags: it never restarts, stops or resizes a guest, never changes its device lines, and never touches a guest that is not this install’s; a running box is marked as it runs. It leaves, and names, a guest the helper would refuse or whose lines it would rewrite, one that is locked or has another marker, and checks each again from the config it reads just before it writes. It counts a guest granted only from the helper’s own answer to that marker. It waits up to 10 s for the answers, and exits 1 when it leaves a guest or the helper does not grant one. –undo clears each claim the helper holds for this install’s guests, through a gpu.release marker the helper answers, then takes that marker off: device lines stay as they are, and the helper no longer writes them.

Usage:
  bb box gpu mark [--check] [--undo] [--on <value>] [--json]

Options:
  --check       Only say what it would mark, or with --undo take off, and why; it changes nothing.
  --undo        Clear the claims the GPU helper holds for this install's guests, and take their shared and whole markers off. Device lines and other gpu tags stay. Needs bb-box-gpu 0.3.0 or later.
  --on <value>  Only this backend, by its ID, such as proxmox-lxc. Every Proxmox LXC backend that is on by default.
  --json        Print JSON.
  --help, -h    Show this help and exit

bb box monitor snapshot

Show BB’s server’s CPU, load, memory, disk and processes, as the Monitor reads them. –json gives the whole reading, with its recent history.

Usage:
  bb box monitor snapshot [--json]

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box monitor health

Show the pressure on BB’s server. Exits 2 when it is critical; with –json it exits 0, and status says.

Usage:
  bb box monitor health [--json]

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit

bb box monitor logs

Show background monitoring’s diagnostic records, oldest first: the last 100, or –limit up to 500. –json gives JSON lines.

Usage:
  bb box monitor logs [--json] [--limit <1-500>]

Options:
  --json           Print JSON.
  --limit <1-500>  How many of the latest records, 1 to 500. 100 by default.
  --help, -h       Show this help and exit

bb box monitor test-alert

Show a labelled preview of a pressure alert in every BB window that is open and visible. Needs background monitoring and its notifications on.

Usage:
  bb box monitor test-alert

bb box monitor history

Show box history (069): whether it reads boxes, how many readings were due, taken, skipped and failed each hour, each box’s newest point, and the room its file uses. –hours chooses how many hours, 24 by default.

Usage:
  bb box monitor history [--json] [--hours <1-168>]

Options:
  --json           Print JSON.
  --hours <1-168>  How many of the last hours to tally, 1 to 168. 24 by default.
  --help, -h       Show this help and exit

bb box sweep

Run the clean-up now: release the boxes of ended threads, finish interrupted work and remove leftovers, and settle and check BB Box’s snapshots against each backend’s.

Usage:
  bb box sweep [--json]

Options:
  --json      Print JSON.
  --help, -h  Show this help and exit