Quickstart

Flash OS images via USB

Put bty on a USB stick with curl | dd. The stick boots any x86 box into the bty wizard, which flashes OS images onto the target’s local disk. The default catalog is the NOSI image set (e.g. pick debian-13-headless for a minimal Debian server), but bty accepts any URL- or oras-served image, so swap in your own catalog when you have one.

curl -fL https://github.com/safl/bty/releases/latest/download/bty-usbboot-pc-x86_64.iso \
  | sudo dd of=/dev/sdX bs=4M conv=fsync

Replace /dev/sdX with your USB stick (check lsblk first), plug into the target, boot from USB, and run the wizard; for the full step-by-step (sha256 check, BIOS boot keys, troubleshooting) see bty via bty-usbboot-pc for x86 or bty via bty-usbboot-rpi for Raspberry Pi.

Deploy bty-server

One command on a Linux host:

sudo uvx bty-lab deploy /opt/bty

That sets up bty-web + withcache via docker-compose. Unlocks PXE-boot for a fleet, image-byte caching across repeat flashes, and hosting a custom catalog (your own image-builder, an internal mirror, …) on top of the USB flow. State lives under /opt/bty/data/.

For a fleet you typically want state on a dedicated drive so an OS reflash leaves the lab intact; prepare the drive first, then point --data-dir at the mount:

# Dedicate a device for bty data-dir
sudo wipefs -a /dev/sdX
sudo mkfs.ext4 -L bty-data /dev/sdX

# Mount bty data-dir at /srv/bty
sudo mkdir -p /srv/bty
UUID=$(sudo blkid -o value -s UUID /dev/sdX)
echo "UUID=$UUID  /srv/bty  ext4  defaults,noatime,nofail  0 2" | sudo tee -a /etc/fstab
sudo systemctl daemon-reload
sudo mount -a

# Deploy bty with a non-default data-dir
sudo uvx bty-lab deploy /opt/bty --data-dir /srv/bty

Full tutorial: bty-lab server setup.

Next steps

The lab is up and you’ve flashed your first target. From here: