BB Box

Setup guide

View prompt

Set up BB Box for me: the BB plugin that gives threads computers of their own, called boxes.

1. Install it: bb plugin install git:https://github.com/ahkohd/bb-box.git@main --yes
2. Follow its bb-box-setup skill. If your skills do not list it yet, find it with bb skill list and read it with bb skill show <id>.
3. Look at the machine that runs BB with bb box doctor, and set up the backend the skill suggests for it: Docker on Linux or in WSL 2 on Windows, microsandbox on a Mac with Apple silicon.
4. Ask me first before anything that needs root, changes BB's settings, or makes Docker boxes privileged containers, which can take over the machine they run on.
5. Prove it: bb box kinds, then bb box acquire with the Linux kind it lists, then bb box run <box> "uname -a", then bb box release <box>.
6. Tell me what you set up, what bb box doctor says, and what is left for me to do.

The quick start: https://bbbox.dev/start/quick-start.md

Why BB Box

• -Each thread gets its own computers. Boxes have the thread’s Git access, its variables and BB itself.
• -Any provider. Docker, Proxmox, microsandbox, Macs with Tart, machines over SSH, or Hetzner Cloud, Namespace and boat.dev.
• -Ready in seconds. A box is usually ready in seconds, and a warm box at once.
• -Shared desktops. You and the agent use the same screen. The agent waits while you have control.
• -Phones and tablets to test apps on. An iPhone or iPad in the iOS Simulator, or an Android device in its emulator. See device boxes.
• -GPUs. A box can share an NVIDIA card or have one to itself, with nvidia-smi, CUDA and PyTorch ready, on supported backends. See GPU boxes.
• -Snapshot, undo and fork. Save a box before a risky change, restore it with an undo, or fork it into a fresh box with its own identity. See snapshots.
• -Resize as you go. More cores, memory, disk or a GPU when a build needs them, from the Box panel, the box’s page or the agent. See resizing a box.
• -Recordings that show the work. An agent records its test run as a short clip, with each step and its result captioned. See Recordings.
• -Keep boxes as your own machines. Threads can run on them, such as an always-on agent with its own desktop.
• -Every machine at a glance. CPU, memory, disk, GPU and processes of every box and machine, in BB’s sidebar. See the Monitor.

bb-box assumes one trusted user. It is not a sandbox for code you do not trust.

Find your way

• -Quick start. Install the plugin, set up Docker and make a box.
• -User guide. The Box panel, desktops and devices, the terminal, images, files and settings.
• -Backends. Docker, Proxmox, microsandbox, Tart, SSH host pools and cloud machines.
• -Reference. Every agent tool, bb box command, setting, kind and check.