AuroraBoot

The Kairos bootstrapper — build images, provision machines, manage the fleet.

AuroraBoot is the official bootstrapper for Kairos. With a single binary you can:

• Build bootable images — ISO, UKI, raw disks, sysextensions — from any Kairos flavor or container image.
• Provision machines over the network via PXE/netboot, Redfish, or plain USB.
• Customize installation media with cloud-configs so machines install themselves unattended.
• Manage a whole fleet from a browser once nodes come online.

Two ways to run it, same binary:

1. One-shot CLI — auroraboot build-iso, auroraboot build-uki, auroraboot netboot, … for quick builds and scripted pipelines.
2. Fleet server — auroraboot web (or docker compose up) gives you a self-hosted dashboard, REST API, node manager, SecureBoot key store and netboot server, all in one place.

---

Getting started with the fleet server

git clone https://github.com/kairos-io/AuroraBoot
cd AuroraBoot
docker compose up --build -d

On first boot AuroraBoot generates an admin password and a node registration token under ./data/secrets/:

cat data/secrets/admin-password
cat data/secrets/registration-token

Open http://localhost:9099, sign in, and the welcome wizard walks you through the three steps: build an artifact, deploy it, manage the nodes that come online.

What you get

• A guided Artifact Builder with ready-made templates for Ubuntu, Fedora, Debian, openSUSE, Alpine, Rocky and Hadron. Pick architecture, model, variant — the UI filters the choices so you only see what Kairos actually supports.
• A deployment surface — download the image, PXE-boot a rack of machines into it, hand it off to a Redfish BMC, or upgrade a node you already registered.
• A node manager — every machine AuroraBoot builds an image for phones home automatically and shows up in the Nodes list. From there you can send commands: upgrade, reboot, reset, apply a cloud-config, or run arbitrary shell with captured output.
• A SecureBoot key store for full PK / KEK / db sets plus TPM PCR policy keys, generated on demand and referenced by name from UKI builds. Keys can be exported as a signed archive and imported on another instance.
• A REST API and Go client mirroring the UI one-to-one, with Swagger UI at /api/docs and a first-class client at pkg/client.

Common settings

Flag / env var	What it does
--listen :8080	HTTP listen address
--data-dir ./data	Where the DB, artifacts, keys and secrets live
--db <dsn>	Override DB DSN (SQLite by default, Postgres supported)
--url https://…	External URL of this instance, injected into cloud-configs so nodes know where to phone home
AURORABOOT_ADMIN_PASSWORD	Override admin password
AURORABOOT_REG_TOKEN	Override registration token

See the full AuroraBoot reference for everything else.

Hadron builds

The Artifact Builder includes a "Hadron custom" template that composes a Hadron OS image from a base release, per-vendor firmware layers and pre-built software layers. Selecting that template opens an inline composer panel inside the normal Kairos wizard:

1. Base image — pick a Hadron release tag from a live dropdown (fetched from GitHub Releases) or enter a fully-qualified custom image ref.
2. Firmware — browse and select from the published hadron-firmware catalog. Items can be reordered and removed.
3. Software layers — browse and select from the published hadron-layers catalog. Same drag-to-reorder, searchable list.
4. Extra Dockerfile — free-form lines appended after the generated COPY instructions, for site-specific customisations.
5. Compose & continue — renders a Dockerfile from the selection (layout-normalising RUN, one COPY --from= per firmware, one per layer, extras appended) and advances to the Configure step of the normal Kairos builder. From there the Dockerfile drives the standard Kairos build pipeline, producing ISOs, UKIs and raw disks exactly like any other artifact.

A live Dockerfile preview is always visible in the panel so you can verify the rendered output before committing to a build.

Cloning Hadron artifacts as templates

Every artifact built from the Hadron composer stores the source composition (hadronBase, hadronFirmware, hadronLayers, hadronExtra) alongside the rendered Dockerfile. Clicking Clone as Hadron on such an artifact row reopens the composer pre-filled with that composition so you can make targeted changes — bump the Hadron version, swap a firmware, add a layer — and then compose a new artifact without rebuilding the recipe from scratch. Non-Hadron artifacts continue to clone through the standard path.

---

Using the CLI

You don't need the fleet server to get value out of AuroraBoot. The historical one-shot CLI is fully preserved, and it's often all you need for a quick build or a one-off netboot.

Netboot a machine from a Kairos release

Run this on a machine on the same network as the target, and let the target PXE-boot:

docker run --rm -ti --net host quay.io/kairos/auroraboot \
    --set "artifact_version=v2.4.2" \
    --set "release_version=v2.4.2" \
    --set "flavor=rockylinux" \
    --set "flavor_release=9" \
    --set "repository=kairos-io/kairos" \
    --cloud-config /path/to/cloud-config.yaml

This downloads the needed artifacts, bakes your cloud-config into a custom ISO, and serves it over the network.

Supported architectures:

• amd64 (default, matches x86_64)
• arm64 (matches aarch64)
• riscv64

Use a container image instead

Point AuroraBoot at any Kairos container image (or your own) and it will boot that:

docker run --rm -ti --net host quay.io/kairos/auroraboot \
    --set container_image=quay.io/kairos/rockylinux:9-core-amd64-generic-v2.4.2

Add -v /var/run/docker.sock:/var/run/docker.sock if you want to use an image already sitting in your local Docker daemon instead of pulling from a remote.

Cross-architecture builds

When pulling images for a different architecture than the host, set arch:

docker run --rm -ti --net host quay.io/kairos/auroraboot \
    --set container_image=quay.io/kairos/alpine:3.21-standard-arm64-rpi4-v3.6.0 \
    --set arch=arm64

Supported: amd64 (default), arm64, and riscv64.

Offline ISO, no netboot

To generate an ISO without starting the PXE server, pass disable_netboot=true:

docker run -v /var/run/docker.sock:/var/run/docker.sock --rm -ti --net host \
    quay.io/kairos/auroraboot \
    --set container_image=quay.io/kairos/rockylinux:9-core-amd64-generic-v2.4.2 \
    --set disable_netboot=true

Configuration file

Everything on the --set flag can also live in a YAML file:

artifact_version: "v2.4.2"
release_version: "v2.4.2"
container_image: "..."
arch: "amd64"  # Optional: architecture to use when pulling container images (amd64, arm64, or riscv64)
flavor: "rockylinux"
flavor_release: "9"
repository: "kairos-io/kairos"

cloud_config: |
  #cloud-config
  install:
    device: "auto"
    auto: true
    reboot: true
  users:
    - name: kairos
      passwd: kairos

Passing - to --cloud-config reads it from stdin, which is handy in CI pipelines.

Other subcommands

# Build an ISO from a Kairos release
auroraboot build-iso --image quay.io/kairos/ubuntu:24.04-core-amd64-generic-v3.6.0 \
    --output ./out --name kairos.iso

# Build a UKI from a container image
auroraboot build-uki --image quay.io/kairos/ubuntu:24.04-standard-amd64-generic-v3.6.0 \
    --output-dir ./out

# Generate a SecureBoot key set
auroraboot genkey my-keys --output ./keys

# Generate a sysextension from a container image
auroraboot sysext my-ext quay.io/myorg/my-tool:latest

# Redfish-driven deploy to a BMC
auroraboot redfish --endpoint https://bmc/redfish/v1 --user admin --pass secret --image kairos.iso

# Extract netboot artifacts from an ISO
auroraboot netboot kairos.iso ./netboot-out

Run auroraboot help for the full list.

Experimental

• Redfish deploy notes

---

Under the hood

• One binary, one container. Go backend, React frontend bundled into the binary at build time and served by the same process. SQLite by default, Postgres optional.
• CLI and fleet server share the same image factory. Both call deployer.Deploy, pkg/uki.Build and pkg/secureboot.GenerateKeySet in-process — whatever the CLI builds, the server builds the same way, and streams the logs into the dashboard as they come out of the deployer.
• Nodes auto-register via the phonehome: cloud-config stage baked into every artifact AuroraBoot produces. First boot → node shows up in the UI. The artifact builder also bakes an explicit allowed_commands list (default: upgrade, upgrade-recovery, reboot, unregister); tick the destructive checkboxes — exec, reset, apply-cloud-config — only on fleets where you need them.
• Deleting a node runs a remote teardown: AuroraBoot sends an unregister command, the agent stops the phone-home service and drops its credentials + cloud-config files, then the DB record is removed. The UI shows live progress. For offline nodes, SSH in and run kairos-agent phone-home uninstall to do the same teardown by hand before force-deleting the record.

---

Development

# Backend (Go 1.26+)
go build ./...
go test ./...

# Frontend (Node 22+)
cd ui
npm install
npm run dev     # Vite dev server on :5173, proxies /api to :8080
npm run build
npm test

# Regenerate the OpenAPI spec
make openapi

# Local Docker build
docker build -t quay.io/kairos/auroraboot:local .
# Skip the Swagger stage for faster iteration:
docker build --build-arg=SWAGGER_STAGE=without-swagger -t quay.io/kairos/auroraboot:local .

---

Documentation & links

• Kairos documentation — the underlying OS
• Getting started with Kairos
• AuroraBoot reference — full CLI reference
• Examples
• Community

---

License

Apache 2.0 — see LICENSE.