bladerunner

README

bladerunner

bladerunner is a standalone Incus VM runner for macOS built directly on Apple Virtualization.framework via github.com/Code-Hex/vz/v3.

It is designed to provide the core behavior of a colima --runtime incus setup without Lima/Colima orchestration overhead:

• Architecture-aware defaults (arm64 and amd64) using Debian 13 (trixie) genericcloud images. Ubuntu and other cloud images remain reachable via --image-url or BLADERUNNER_BASE_IMAGE_URL.
• Incus daemon bootstrapped inside the guest via cloud-init.
• Localhost-accessible SSH and Incus HTTPS endpoints via virtio-vsock port forwarding.
• Incus web dashboard availability through the forwarded API endpoint.
• Optional bridged networking (for transparent L2 presence) when signed with com.apple.vm.networking.
• Startup report generation with VM, network, and access details.
• Optional GUI console window (StartGraphicApplication) with serial output logged to file.
• Rotating structured logs with stage-level observability and live progress indicators for long-running tasks.
• No OpenID setup by default.

Requirements

• Apple Silicon Mac (M1/M2/M3/M4) - Intel Macs not supported

• macOS 13+ (Ventura or later)

• Xcode Command Line Tools (includes codesign utility)

  xcode-select --install
  

• Binary must be code-signed with Virtualization entitlement (automatic with Homebrew)

• For bridged networking, additional VM networking entitlement required

Installation

Homebrew (Recommended)

brew install stuffbucket/tap/bladerunner

The binary is automatically signed with required entitlements during installation.

Build from Source

Requires Xcode Command Line Tools:

xcode-select --install

Build and sign:

make build
make sign

Or manually:

go build -o bin/br ./cmd/bladerunner
codesign --entitlements vz.entitlements -s - bin/br

Run

Default (shared network + localhost forwarding):

br start

With GUI console window:

br start --gui

Bridged network on en0:

br start --network-mode bridged --bridge-interface en0

Custom image path (raw disk image):

br start --image-path /path/to/base.raw

Custom log file path:

br start --log-path /tmp/bladerunner.log

Optional log level. Accepts debug, info, warn (alias warning), or error (case-insensitive). Unknown or unset values default to info:

BLADERUNNER_LOG_LEVEL=debug br start

Access

After startup, the tool prints a report and writes JSON report data to:

• ~/.local/state/bladerunner/startup-report.json

Key defaults:

• Incus API/UI endpoint: https://127.0.0.1:18443
• SSH endpoint: 127.0.0.1:6022
• Dashboard URL: https://127.0.0.1:18443/ui/
• Log file: ~/.local/state/bladerunner/bladerunner.log (rotated with compression)

Example SSH:

ssh -p 6022 incus@127.0.0.1

Example REST call:

curl --cert ~/.local/state/bladerunner/client.crt --key ~/.local/state/bladerunner/client.key -k https://127.0.0.1:18443/1.0

Notes

• The default base image is the Debian 13 (trixie) genericcloud qcow2 (incus and incus-client ship in trixie main, so no third-party apt repos are needed). Override with --image-url or BLADERUNNER_BASE_IMAGE_URL to use Ubuntu 24.04 or another distribution.
• The base image can be raw or qcow2 format. qcow2 images are automatically converted to raw via qemu-img.
• First boot can take several minutes while cloud-init installs and configures Incus.
• A pre-baked bladerunner guest image (Debian Trixie + Incus + br-agent, built by scripts/build-guest-image.sh and published via the build-guest-image workflow) is the future default. While that release pipeline is bootstrapping it is opt-in: set UseHostedGuestImage (or pass --image-url with the GitHub Release URL) to use it. Once guest-image-latest is published the default will flip.
• Downloaded base images are SHA-256 verified against a sidecar .sha256 file. The check is strict for upstream Debian URLs and tolerant of a missing sidecar for GitHub Release URLs during the bootstrap window.
• br status surfaces the pre-baked image build date from /etc/bladerunner-image-version when present.
• GUI output is handled by VZ graphics window; serial console is logged at console.log.
• Extended operations (download, VM readiness, Incus readiness) show live progress indicators in terminal.

Documentation

Index

• Variables

Variables

var License string

var Notice string