bty-lab 0.2.10

Flash images onto target disks, locally or over PXE

bty - flash images onto target disks, locally or over PXE

Bare-metal provisioning toolkit. Flashes pre-built ("cooked") system images onto target disks (locally from a USB stick or remotely over PXE) and configures them via cloud-init or CIJOE workflows. Designed for both ad-hoc one-off provisioning and DevOps fleet operation.

bty is one Python package: the bty module, distributed on PyPI as bty-lab, with four console-script entry points:

• bty: main CLI (image inspection, target discovery, flashing, provisioning).
• bty-tui: terminal UI (requires the tui extra).
• bty-web: HTTP server with browser UI (requires the web extra).
• bty-ctl: command-line client for a remote bty-web server (bty-ctl login, bty-ctl logout, future fleet ops).

Plus a sibling appliance-image builder under bty-media/ that produces the bootable USB live image and the server appliance image.

Install

pipx install bty-lab            # CLI + bty-ctl, zero third-party Python deps
pipx install "bty-lab[tui]"     # adds the bty-tui terminal UI
pipx install "bty-lab[web]"     # adds the bty-web HTTP server
pipx install "bty-lab[all]"     # everything

The CLI flow (bty list disks, bty inspect image, bty flash --dry-run) needs only Python 3.11+ and stdlib; full flashing (bty flash --yes) relies on system binaries (dd, qemu-img, zstd, lsblk, etc.) the operator's distribution is expected to provide.

Status

Pre-1.0 but actively shipping. Wheels and appliance images publish to PyPI + GitHub Releases on every tag, and the server + client + PXE-chain end-to-end flow runs in CI on every push. The CLI surface (bty list, bty inspect, bty flash) and the bty-web HTTP/iPXE/PAM-auth surfaces are stable enough to use in homelab / CI fleets. Wire formats and CLI flags may still shift between minor versions until 1.0; the schema_version field on --json output and the Machine wire type are the things to watch. See PLAN.md for the milestone-by-milestone roadmap.

Planning and design

• PLAN.md: roadmap and design intent.
• docs/: full documentation (Sphinx + MyST).

Development

uv is the project's dependency manager. Install it via pipx if you don't already have it:

pipx install uv

Then sync the dev environment:

uv sync --all-extras --group dev

Run the test suite, linter, and type-checker:

uv run pytest
uv run ruff check
uv run mypy src

Documentation

The docs tooling installs as a separate pipx app:

pipx install ./docs/tooling

Then, from inside docs/:

bty-docs-serve              # live-rebuild dev server on :8000
bty-docs-build-html         # one-shot HTML build
bty-docs-build-pdf          # one-shot PDF build (requires LaTeX)

License

GPL-3.0-only.