Health checks

What bb box doctor, and each backend’s check on the settings page, can report, by check ID. A part in angle brackets, such as <vmid>, stands for a value, such as a template’s VMID. Each check is ok, a warning, a failure, or skipped when one before it failed; a warning leaves the doctor passing.

bb-box

ID	Name	What it checks
doctor	Checks	A backend’s checks did not finish within their time limit.
config.<path>	Settings	A part of BB Box’s configuration that needs fixing, by its path, such as general.defaultKind.
offers.<kind>	Offers of <kind>	Where several backends offer a kind: they agree on what the kind promises, and each has the features it requires.
overlap.<backend>.<backend>	<backend> and <backend>	Two backends whose boxes could take the same guest IDs or addresses.
warm.<kinds>	Warm pool of <kinds>	A warm pool that has fewer ready boxes than its count asks for, and no room for another.
sizes.<kind>.<preset>	Box sizes	A Linux preset with less than 2 GiB memory, so its boxes can run out of memory as they become BB machines.
box-files	Files for every box	The files BB Box writes into each box as it joins BB, and whether the last write worked.
box-history	Box history’s file	Where BB Box will keep each box’s readings over time (069): box-history.db beside its database, attached with its own cap, or its database itself where BB’s handle refused to attach the file.
box-log	Box log	Where BB Box keeps who stopped, started, resized and released each box (069): box-log.db beside its database, or its database itself where BB’s handle refused to attach the file; and whether its writes failed.
snapshots	Snapshots’ records	Where BB Box keeps its records of snapshots and their operations (070): snapshots.db beside its database, or its database itself where BB’s handle refused to attach the file; and whether its writes failed. While it cannot write them, BB Box takes and deletes no snapshots.
snapshots.locked.<box>	<box> locked	A box with snapshots whose guest its provider left locked (070), as Proxmox does when a task dies part way: BB Box takes, deletes and restores none of its snapshots until the lock is gone, and only root on the host can remove it. Says the host’s command.
snapshots.restore.<box>	Restore of <box>	A restore of a box that BB Box could not confirm (070), as when BB Box restarted while Proxmox rolled the box back: it keeps the snapshots it used and checks again at each sweep.
gpu-userspace	NVIDIA userspace	How many boxes with a GPU have NVIDIA’s userspace for their host’s driver, as BB Box reads it in each running box at this check (071). BB Box never updates a box’s userspace by itself.
gpu-userspace.<box>	NVIDIA userspace in <box>	A box with a GPU whose NVIDIA userspace is not the host’s driver, is half-installed, or whose last update did not finish, so nvidia-smi and CUDA fail or may fail in it (071). A stopped box is named as BB Box last read it. It says the command that updates it: bb box gpu update.
join.<box>	<box> joining BB	A box that did not join BB at its first try. BB Box tries again after 30 s, 2 min, 10 min and 30 min, then every 30 minutes for up to 24 hours from the first failure, when what failed can pass, such as a DNS lookup that timed out. It warns while it tries, and when other boxes on the same backend joined. It fails once no box on the backend can reach BB, which is a setup problem.
identity-reset.<box>	Identity reset of <box>	A box of BB Box’s whose identity reset at a boot (070), which took its BB machine with it: BB Box keeps the box and enrols it again as a new BB machine. It warns once that is done, and fails until it is. A box that is not a copy of another should never reset.
images.nightly	Nightly rebuilds	When bb box images refresh last ended. It warns when no run ended for 8 days.
images.bb-update	Refresh after a BB update	After a BB update, which Linux images have another build of BB’s app than BB’s server gives, and when their refresh starts. Only while Rebuild each night is on.
images.<backend>/<ref>	Rebuild of <backend>/<ref>	A standard image whose last rebuild failed, or waits for room.
images.bake.<image>.<backend>.<kind>	Build of <image> for <kind> on <backend>	A project image whose last build failed. Its boxes run its script as they start meanwhile.
device-hub.<box>	Device Hub in <box>	An ios box’s macOS host has no Device Hub running (063): it takes the device’s pasteboard, and quitting it shuts the device down, so the device server kills it within 5 s of its start. Says how often it has.
device.<box>	Device server of <box>	A device box’s server (063): the version it runs against the one this BB Box delivers, a delivery waiting for a person or a recording, a version marked bad after it did not answer, and a server its service manager gave up on.
encoder.<mac>	Video encoder on <mac>	A Mac’s video encoder, shared by every iOS device BB Box streams on it (064): its budget, from the chip or a probe, how much of it the streams use, and which are shown at a lower resolution to keep within it.
monitor	Monitor	The Monitor’s settings (066): whether it is on, how often machine status reads while it is open, and whether background monitoring and its notifications are on.
monitor.background	Background monitoring	While background monitoring is on: when it last wrote its minute’s summary of BB’s server’s CPU and memory, and whether its last sample or write failed.
spares.<kind>	Spare <kind> boxes	A kind’s spares (032, 063): how many BB Box keeps, how many are ready or being made, and what each costs while it waits. For ios and android it says when spares are off, as they are by default. It warns when the kind has fewer than its count and why.
spares.image.<image>.<backend>.<kind>	Spare of <image> for <kind> on <backend>	A project image’s spare whose build failed to start a box, so BB Box makes none of that build for a day. Its boxes start from the build meanwhile.
tailnet.client	OAuth client	Tailscale signs in the OAuth client in the General settings, with which BB Box makes a single-use key for each machine it makes.
tailnet.devices	Devices	This install’s devices on the tailnet, which BB Box removes when their machine went without logging out, and how many other devices carry the same tags, unnamed: BB Box leaves those alone.

SSH host pool

ID	Name	What it checks
devices.<mac>	iOS devices on <mac>	What a Mac offers iOS devices, as BB Box last measured it there (065): the iOS Simulator, and a hardware or software H.264 encoder for their video. A Mac that cannot run the Simulator or stream lends no ios slot.
ssh.key	SSH key	BB Box’s SSH key reads, and, where BB Box made it, its public key to install.
machines	Machines	At least one machine is listed.
docker	Docker	Whether the pool’s Linux machines lend Docker to their boxes.
xcode	Xcode	Whether the pool’s Macs have Xcode.
machine.<machine>.ssh	<machine>: SSH	The machine answers over SSH with its pinned host key.
machine.<machine>.sizes	<machine>: room for each kind	The machine holds a box of each of its kinds at the default size.
machine.<machine>.helper	<machine>: helper	BB Box’s helper is installed on the machine, at this BB Box’s version.
machine.<machine>.arch	<machine>: architecture	The machine’s architecture is the one its kinds need.
machine.<machine>.tools	<machine>: tools	The tools its kinds need are on the machine.
machine.<machine>.docker	<machine>: Docker	Docker runs on the machine, for its boxes.
machine.<machine>.state	<machine>: state	Whether the machine is free, lent, being reset or out of service.
machine.<machine>.filevault	<machine>: FileVault	On a Mac, FileVault is off, so it signs a box user in after a restart.
machine.<machine>.signin	<machine>: sign-in	On a Mac, the next box user is signed in at the console.
machine.<machine>.fulldisk	<machine>: Full Disk Access	On a Mac, the helper has Full Disk Access, which a reset needs.
machine.<machine>.sip	<machine>: System Integrity Protection	On a Mac, whether System Integrity Protection is on, and so whether BB Box can grant box users’ programs macOS permissions (058).
machine.<machine>.slots	<machine>: iOS slots	On a Mac whose line lists ios (064): that its iOS slots are set up, whether it lends slots or is lent whole, its slots held, ready, making and sweeping, the iOS runtime and seed they are made with, each held slot’s load, and what its last sweeps found and left.
machine.<machine>.homes	<machine>: people’s homes	On a Mac, box users cannot enter any person’s home, such as an administrator’s with BB’s or an agent CLI’s credentials.
machine.<machine>.xcode	<machine>: Xcode	On a Mac, Xcode and its iOS runtime.
machine.<machine>.screensharing	<machine>: Screen Sharing	On a Mac with desktops, Screen Sharing is on.
machine.<machine>.grants	<machine>: Cua Driver’s grants	On a Mac with desktops, Cua Driver has Accessibility and Screen Recording.
machine.<machine>.input	<machine>: viewer’s input	On a Mac with desktops, a viewer’s keys and clicks reach the desktop.

Tart

ID	Name	What it checks
devices.<mac>	iOS devices on <mac>	What a Mac offers iOS devices, as BB Box last measured it there (065): the iOS Simulator, and a hardware or software H.264 encoder for their video. A Mac that cannot run the Simulator or stream lends no ios slot.
tart.ssh-key	SSH key	BB Box’s SSH key for the Macs reads, and its public key to install.
tart.hosts	Macs	At least one Mac is set up.
host.<mac>	Mac <mac>	The Mac answers over SSH, is Apple silicon, and has Tart.
image.<mac>.<kind>	<kind> image on <mac>	The VM a kind’s boxes are cloned from is on the Mac, of the right OS, and not too old. For the iOS image, also that it offers iOS devices, built on the macOS image’s current build, with an idb_companion and Xcode an image check has passed together.
forks.<mac>	macOS forks on <mac>	Whether the Mac’s diskutil can attach a fork’s disk, so BB Box can clean it of its source’s identity before the fork first boots (070 unit 9). Without it, macOS boxes there take and restore snapshots, but make no forks and keep none past a release.
spotlight.<mac>	Spotlight on <mac>	Whether Spotlight indexes the folder of Tart’s VMs, so it opens each new VM’s disk, and how to keep it out (F-12).
qemu.<mac>	QEMU on <mac>	QEMU, the Hypervisor framework and UEFI firmware, for Windows boxes on the Mac.
qemu-video.<mac>	Windows video on <mac>	BB Box’s build of bb-box-stream on the Mac, which gives Windows boxes video from QEMU’s VNC server (#865).
capacity.<mac>	Room on <mac>	Room on the Mac for a macOS box at its default size.
sizes.<mac>	Room for each kind on <mac>	The Mac holds a box of each kind at its default size.
ios-hosts.<mac>	Shared iOS hosts on <mac>	The shared iOS hosts on the Mac (064), or on Namespace (065): each host’s state, its slots held, ready, making and sweeping, its free disk and memory, and each held slot’s cores, memory and home; Namespace’s host’s end and how its video is encoded; or, with none, whether one can start.

Namespace

ID	Name	What it checks
devices.<mac>	iOS devices on <mac>	What a Mac offers iOS devices, as BB Box last measured it there (065): the iOS Simulator, and a hardware or software H.264 encoder for their video. A Mac that cannot run the Simulator or stream lends no ios slot.
namespace.token	API token	Namespace’s API answers to the token in BB Box’s settings.
namespace.machines	Machines	The Namespace machines BB Box has, each with its age and when it ends, and any no box claims.
namespace.limits	Workspace limits	The Mac cores and memory the workspace allows at once and has in use, read from Namespace, from which BB Box refuses a Mac up front; a warning when the token may not read them.
namespace.images	Linux images	BB Box’s Linux images in the workspace’s registry: when each was built, whether a new one is due, and whether one is being built.
ios-hosts.<mac>	Shared iOS hosts on <mac>	The shared iOS hosts on the Mac (064), or on Namespace (065): each host’s state, its slots held, ready, making and sweeping, its free disk and memory, and each held slot’s cores, memory and home; Namespace’s host’s end and how its video is encoded; or, with none, whether one can start.

Proxmox LXC

ID	Name	What it checks
proxmox.api	Proxmox API	The API answers at its URL, with a certificate BB Box trusts, and the token works.
proxmox.node	Node	The node exists and is online.
proxmox.memory	Node memory	How much of the node’s memory is free beyond the reserve.
proxmox.pool	Resource pool	The resource pool exists and the token may use it.
proxmox.bridge	Network bridge	The bridge exists on the node.
proxmox.vmids	VMID range	The VMID range is free of guests BB Box did not make.
proxmox.sizes	Room for each kind	The node holds a box of each kind at its default size.
proxmox.snapshots	Snapshots	Whether the token may take and restore snapshots, with VM.Snapshot and VM.Snapshot.Rollback on the pool, and what each template’s storage restores: any snapshot on LVM-thin, Ceph RBD, BTRFS and qcow2 files, the newest only on ZFS, none on LVM or raw files (070).
template.<vmid>	<flavour> template <vmid>	A template is there, is a template, and has what its kind needs.
template.<vmid>.image	Image of <flavour> template <vmid>	The template’s image record: its age, pins and tools, against this BB Box’s.
proxmox.gpu-helper	Host’s GPU helper	Where host/setup-gpu.sh has installed the GPU helper, bb-box-gpu: it reported under 3 minutes ago, speaks a protocol this BB Box speaks, serves this install’s pool, runs on a pve-container version it was tested on, and has writes on. It warns while the helper runs with writes off, a dry run, and on a node with cards and no helper, where servers get no GPU (071).
proxmox.gpu-cards	Boxes on their cards	Where the GPU helper reports: every running box with a GPU lists its claimed card in nvidia-smi, as BB Box checks every 10 minutes, and the helper reports no running guest on another card’s lines. It fails naming each box on the wrong card or none (071).
proxmox.gpu-migration	Markers on GPU guests	Where the GPU helper, bb-box-gpu, reports: every guest of this install whose device lines name a card carries the marker bb box gpu mark gives it, the helper answered each, and, in its dry run, it would write no guest (071). It names the guests that fail.
proxmox.gpu-report	Host’s GPU report	The host’s report of each GPU’s memory, which the GPU helper, bb-box-gpu, or else bb-box-gpu-memory.timer writes in a VM’s notes: there, current, and naming each GPU.
gpu.<gpu>	GPU <gpu>	A GPU’s free memory, as BB Box last read it in a GPU desktop, against what a GPU desktop needs.
gpu.<gpu>.whole	GPU <gpu> whole	A card a box holds whole has no other holder. It fails, naming the guests, when a claim went wrong (071).
ssh.key	SSH key	BB Box’s SSH key reads, and, where BB Box made it, its public key to install.

Proxmox QEMU

ID	Name	What it checks
proxmox.api	Proxmox API	The API answers at its URL, with a certificate BB Box trusts, and the token works.
proxmox.node	Node	The node exists and is online.
proxmox.memory	Node memory	How much of the node’s memory is free beyond the reserve.
proxmox.pool	Resource pool	The resource pool exists and the token may use it.
proxmox.bridge	Network bridge	The bridge exists on the node.
proxmox.vmids	VMID range	The VMID range is free of guests BB Box did not make.
proxmox.sizes	Room for each kind	The node holds a box of each kind at its default size.
proxmox.snapshots	Snapshots	Whether the token may take and restore snapshots, with VM.Snapshot and VM.Snapshot.Rollback on the pool, and what each template’s storage restores: any snapshot on LVM-thin, Ceph RBD, BTRFS and qcow2 files, the newest only on ZFS, none on LVM or raw files (070).
template.<vmid>	<flavour> template <vmid>	A template is there, is a template, and has what its kind needs.
template.<vmid>.image	Image of <flavour> template <vmid>	The template’s image record: its age, pins and tools, against this BB Box’s.
proxmox.android-kvm	KVM for Android	Where Android templates are listed, the host allows nested virtualization, as the linux-kvm setting says: the Android emulator needs KVM.
proxmox.android-disk	Disk for Android	The storage of each Android template has room beyond the reserve for a refresh’s build and trial boxes and an Android box in use.
ssh.key	SSH key	BB Box’s SSH key reads, and, where BB Box made it, its public key to install.

Docker

ID	Name	What it checks
gpu.<gpu>.whole	GPU <gpu> whole	A card a box holds whole has no other holder. It fails, naming the guests, when a claim went wrong (071).
gpu.<gpu>.limit	GPU <gpu> boxes	A card has no more boxes than the boxes per card. It warns, naming the boxes over the limit, which keep running while no new box goes on the card (071).
docker.cli	docker CLI	The docker CLI runs on BB’s server.
docker.daemon	Docker daemon	The Docker host answers, runs Linux containers, and its architecture.
docker.attach	Attached output	On a Windows machine, a Docker host at tcp://127.0.0.1, or a BB machine whose Docker there is, returns an attached command’s output. WSL’s localhost forwarder does not: docker run and docker exec print nothing and exit 0. For a BB machine, set machine-docker-host to wsl://<distro>.
docker.ssh	SSH connection reuse	Over ssh://, whether the docker calls share one SSH connection.
docker.limits	CPU and memory limits	Docker can limit a container’s CPU and memory, as each box needs.
docker.cpuset	Cores a box sees	Docker can pin each box to as many CPUs as it has cores, so nproc in a box says its cores.
docker.apparmor	Programs in boxes under the host’s AppArmor	A setgid program in a box, as sudo runs, works under the Docker host’s AppArmor profiles, which on a host that is itself a container cannot name a box’s files.
docker.lxcfs	Memory and CPUs a box sees	The host runs LXCFS, so free, /proc/meminfo and /proc/cpuinfo in a box say its own memory and CPUs, and no running box’s LXCFS files have broken.
docker.network	Network <network>	BB Box’s network for its boxes, made by BB Box.
docker.privileged	Docker in boxes	Whether boxes are privileged, so they can run Docker inside.
docker.one-backend	One backend for this daemon	No other backend of this install that is on reaches the same Docker daemon, known by its engine ID, its name and its Docker root together. Where two do, BB Box places GPU boxes there through the one whose ID sorts first, as each would count only its own boxes on the cards; boxes with no GPU are made through either (071).
docker.gpus	GPUs	The NVIDIA cards Docker lists as CDI devices, for GPU boxes, as nvidia-smi in a container given them reads them; whether every box can open every card there; another install’s GPU boxes on the host; and a box with a whole card that BB Box cannot match to a card it reads, which stops GPU boxes there (071).
docker.capacity	Room on <host>	Room on the host for a Linux box at its default size.
docker.sizes	Room for each kind	The host holds a box of each kind at its default size.
image.<image>	Image <image>	An image a kind runs is on the host, built by BB Box’s build script, and not too old.

Hetzner Cloud

ID	Name	What it checks
hetzner.api	Hetzner Cloud API	The API answers and the token reads the project.
hetzner.reach	Reaching hosts	How BB Box reaches a host’s Docker: over the tailnet, or over the internet from the addresses in SSH from.
hetzner.unclaimed	Servers no host claims	Servers with this install’s label that are not hosts BB Box knows. The sweep adopts a host’s server, as after lost storage, and deletes any other 10 minutes after it was made.
hetzner.type	Server type <type>	The hosts’ server type is sold at the location, with its size and price.
hetzner.image	Host image	The snapshot new hosts start from, with Docker, Tailscale and the box images in it: its age, the snapshots kept and their cost, and the last build.
hetzner.arm-type	Server type <type>	The Arm hosts’ server type, for linux-arm64 boxes, is an Arm type sold at the location, with its size and price.
hetzner.arm-image	Arm host image	The snapshot new Arm hosts start from: its age, the snapshots kept and their cost, and the last build.
hetzner.hosts	Hosts	Each host BB Box made: its state, age, boxes and cost this month.
hetzner.spend	This month’s spend	What the hosts cost this month before VAT, against the monthly limit.
hetzner.host.<host>	Docker on <host>	A host’s Docker, as the Docker backend’s checks find it.

microsandbox

ID	Name	What it checks
image.<image>	Image <image>	An image a kind runs is on the host, built by BB Box’s build script, and not too old.
microsandbox.host	Host <host>	The host answers, runs Linux on x86_64, and its cores, memory and free disk.
microsandbox.msb	msb	BB Box’s msb is installed on the host at the release this BB Box pins.
microsandbox.kvm	KVM	The host has /dev/kvm, and BB’s user may use it.
microsandbox.snapshots	Snapshots	The host’s msb is the release whose snapshots BB Box’s checks measured, so BB Box takes, restores, forks and deletes snapshots there.
microsandbox.lxc	LXC	The host is an LXC container, where msb’s snapshots and flat roots fail.
microsandbox.overcommit	Memory overcommit	Above 1, whether it applies on the host: a Mac keeps the memory a box has used, so BB Box counts each box there at its full size.
microsandbox.capacity	Room on <host>	Room on the host for a box at its default size.
microsandbox.sizes	Room for each kind	The host holds a box of each kind at its default size.

boat.dev

ID	Name	What it checks
boat.api	boat.dev API	boat’s API answers to the API key in BB Box’s settings, and on which plan.
boat.limits	Plan limits	What the boat plan allows now: sandboxes at once, starts left in each window, the sizes and their prices, and the trial’s compute hours left.
boat.bb	Reaching BB	Whether boat’s sandboxes can reach BB’s server, through the tailnet or a URL on the internet, so boat boxes become BB machines. It warns when BB’s URL is on a private network and the tailnet is off.
boat.android	Android	Whether boat.dev offers Android boxes: the Android SDK’s licence accepted in its settings, its Android template and the devices in it, and the largest size the plan allows them.
boat.templates	Templates	The stopped template sandbox each kind’s boxes fork: when it was built, whether a new one is due, and whether one is being built.
boat.sandboxes	Sandboxes	The boat sandboxes BB Box holds for its boxes, each with its state, size, price an hour and age, and any no box claims.