Decision records
Each record gives the context, the decision and its consequences, as they were when it was made. A decision that changes gets a new record, and the old one says which parts the new one supersedes or extends. “Now” says which records still stand as written. The current design as a whole is in the architecture.
| Decision | Now | |
|---|---|---|
| 001 | The core does not care who the provider is | Current |
| 002 | BB is the coordinator | Current |
| 003 | Boxes live until their thread ends or they are released | Current |
| 004 | Acquire and release, for virtual and real machines | Current |
| 005 | The first backend runs Linux boxes as unprivileged LXC containers on Proxmox VE | Current |
| 006 | The Linux GPU desktop runs Xorg with NVIDIA’s driver, streamed by x0vncserver | Partly superseded by 021 |
| 007 | The desktop stream is a typed transport, relayed through the plugin | Partly superseded by 011 and 056 |
| 008 | You and the agent share one desktop, with one controller at a time | Partly superseded by 015, 038 and 045 |
| 009 | A conformance suite and a doctor check for every backend | Partly superseded by 016 |
| 010 | The repository is publishable at all times | Current |
| 011 | Interface v1: shared kinds, routes and displays | Partly superseded by 012, 015, 016 and 028 |
| 012 | A kind names what it promises, and offers may add features | Partly superseded by 027 and 041 |
| 013 | Docker boxes run unprivileged, without systemd | Superseded by 031 and 041, but for no systemd and no dockerHost |
| 014 | Boxes enrol through BB’s machine provider API, when claimed | Partly superseded by 032 |
| 015 | Computer use drives a pinned Cua Driver through bb-box’s own tools | Partly superseded by 022 and 039 |
| 016 | Changes from building Interface v1: jump hosts, first keys, setup, stale releases, facts | Current |
| 017 | Boxes clear BB’s daemon lock and PID file at boot | Current |
| 018 | Guests name their install and their box, and backends check both before acting | Current |
| 019 | The sweep restores lost records, and only BB ends a thread | Partly superseded by 025 |
| 020 | Control belongs to one viewer, and a GPU desktop is retried on another GPU | Partly superseded by 043 |
| 021 | A desktop whose VNC server cannot resize is resized by its backend | Current |
| 022 | A reference follows its element through a rename, not into another row | Partly superseded by 023 |
| 023 | A reference follows its element through its own rename | Partly superseded by 024 |
| 024 | An action on an element renamed out of sight is refused once | Current |
| 025 | A restored box enrols again, keyed by its box ID | Partly superseded by 026 |
| 026 | A restored box enrols once it answers | Current |
| 027 | A kind says when it has a desktop, and a plain box has no qualifier | Partly superseded by 029 and 041 |
| 028 | A box’s size is chosen when it is made, from presets per kind | Current |
| 029 | Configuration is one checked document in bb-box’s storage, set through its page and CLI | Current |
| 030 | A Mac runs desktop commands through launchctl asuser |
Current |
| 031 | Docker boxes are reached through docker exec |
Current |
| 032 | Spare boxes are enrolled ahead, and BB shows them until claimed | Current |
| 033 | A thread can start on a new box, from BB’s new-thread screen | Partly superseded by 034 |
| 034 | A box a thread is working on is released or stopped only when forced | Current |
| 035 | A box’s terminal has its PTY on BB’s server, and the plugin keeps the shell | Current |
| 036 | Your machines are boxes you own, kept as BB machines | Current |
| 037 | A panel keeps a box’s desktop and terminal across tab switches | Current |
| 038 | The agent can take control back when asked | Current |
| 039 | Windows desktops are clones of a template that is not generalized | Current |
| 040 | Linux on arm64 has kinds of its own | Partly superseded by 041 |
| 041 | Every Linux box has Docker, started on first use | Current |
| 042 | A Docker host can be a BB machine, reached through BB | Current |
| 043 | A viewer has 5 s to come back after the box ends its connection | Current |
| 044 | A box can be asked for on one provider | Current |
| 045 | A person’s control lasts through a restart of the plugin | Current |
| 046 | Windows on a Mac runs in QEMU, in the Tart backend | Current |
| 047 | A physical Mac is an SSH pool machine, lent with a new user at its console | Current; a real Mac’s live check is to come |
| 048 | A Wayland desktop is Sway with floating windows, streamed by wayvnc | Current |
| 049 | A project’s image is a script on the standard image, and images are rebuilt when stale | Current |
| 050 | A box can join the operator’s tailnet as an ephemeral node | Not built yet, but for TUN in Proxmox LXC templates |
| 053 | microsandbox runs light Linux boxes as microVMs | Current, amended: an option beside Docker, not the default |
| 054 | Windows images are refreshed in a box of the current build | Being built |
| 055 | Cloud boxes run on cloud hosts first, and a cloud VM per box later | Not built yet |
| 056 | Linux X11 desktops add a Selkies stream, and RFB stays for the rest, tuned | Current, amended: video for every viewer, on by default |
| 057 | Linux boxes can be Proxmox VMs, for their own kernel | Proposed |
| 058 | A Mac with SIP off grants its box users macOS permissions | Current |
| 059 | Agents record their desktop box with box_record | Accepted |
| 060 | Every desktop streams as video through one viewer | Accepted |
| 061 | A box can be resized after it is made, live where its backend can, and restarted only when asked | Accepted |
| 062 | Docker boxes are pinned to their cores, and see their memory through LXCFS where the host has it | Accepted |
| 063 | Device boxes: one iOS Simulator or Android emulator per box, in a frame in the panel, shared with the agent | Accepted; not built yet |
| 064 | iOS shared hosts: ios boxes as macOS users with their own device, many to a Mac, on pool Macs, Tart VMs and Namespace Macs | Proposed; decision 14 superseded by 065 |
| 065 | Macs say what they offer, measured, and iOS streams in software where a Mac has no encoder | Proposed |
| 066 | The Monitor is Beacon moved into bb-box, and a container is judged by its own cgroup | Accepted |
| 067 | The settings page is an overview, with a page one step in for each backend, kind and option | Accepted; built |
| 068 | A boat.dev box is a sandbox forked from a template sandbox, held on a renewed auto-stop and deleted on release | Proposed; being built |
| 069 | A box has a page of its own, and the Boxes page says how each box is now | Accepted; being built |
| 070 | A box’s snapshots are bb-box’s own records, taken by each backend’s own mechanism, and kept with the box unless the person keeps them | Proposed; not built yet |
| 071 | A GPU is part of a box’s size, on any Linux box: none, shared or a whole card, chosen when it is made and changed by Resize | Accepted, with the owner’s answers; not built yet |
| 072 | voxl streams Linux X11 desktops, beside today’s streamers, as an option the owner picks | Withdrawn by the owner; unit V1 removed |
| 073 | Recordings draw the pointer, keys and zooms from the event log | Accepted; amended 8 November 2026, including Inter and the owner’s icons; the still disc and a field too large to zoom are superseded by 079; a zoom before a window has painted, a result that stays until the next step, and two captions for one moment are superseded by 080; still stretches alone where the pointer is drawn, captions that keep their places, the wait before typing into a clicked field and a zoom held until a change elsewhere are superseded by 081; device boxes not yet |
| 074 | A box has a files view: the box user’s own files, in the panel | Accepted; the view itself is superseded by 075 |
| 075 | The files view is the editor plugin’s own UI, reading the box | Accepted; creating, renaming and a narrow window are in 076; initial loading and placement are superseded by 077 |
| 076 | The files view can create, rename and delete, and a narrow window shows one surface | Accepted |
| 077 | Files draw one level before walking names; cached reopen and a right-hand tree | Accepted |
| 078 | Files keep the workspace in memory across panel switches | Accepted |
| 079 | A click ring fades, and a large field zooms on its line | Accepted |
| 080 | A window is zoomed once it has painted, and a result fades | Accepted; a result that fades after 2.5 seconds, and a flat window after a click in its field, are superseded by 081 |
| 081 | A recording is cut to its actions, and its captions keep clear | Accepted |