The live environment starts

The ISO boots CentOS Stream 9 as the live environment — regardless of which distro you plan to install. The live environment includes ZFS kernel modules (precompiled for the live kernel), all installer tooling, the web UI, and the darksite package mirrors. On desktop profile ISOs, GNOME starts with autologin as user live (password: live). On server ISOs, you get a TTY login. In both cases, Firefox or a terminal prompt points you to http://localhost:8080 where the web UI is already running.

Pick your target OS

The top of the installer shows a grid of distribution cards. Each card shows the distro name, version, and whether it can be installed offline or requires internet. The currently supported distributions are:

CentOS Stream 9 (offline) — the default. Enterprise-grade RHEL upstream. Most tested, most stable.

Fedora 41 (offline) — bleeding edge. Latest kernel, latest packages.

Debian 13 Trixie (offline) — the universal OS. Stable, predictable, huge package archive.

Rocky Linux 9 (offline) — RHEL binary-compatible. For shops that need RHEL without the subscription.

RHEL 9 (internet required) — Red Hat Enterprise Linux. Requires Red Hat portal credentials or an activation key.

Ubuntu 24.04 (offline) — Canonical's LTS. Popular for desktops and cloud workloads.

Arch Linux (internet required) — rolling release. Always the latest everything. No darksite (by design — rolling releases cannot be frozen).

FreeBSD (internet required) — not Linux, but supported. Native ZFS, jails, bhyve hypervisor.

OpenBSD (experimental) — security-focused BSD. Experimental support.

Local AI — early preview

Below the distro grid is an AI assistant toggle. When enabled, the installer will set up Ollama, download the llama3.1:8b model (trained on kldload documentation), and install Open WebUI for a browser-based chat interface. This is entirely optional and requires 16 GB of RAM and internet access during the initial model download (~6 GB). After first boot, the AI runs completely offline.

The AI model selection is hardware-gated. The web UI queries the system's RAM and VRAM (via nvidia-smi if an NVIDIA GPU is detected) and disables model checkboxes that the hardware cannot support. General Chat (8b) is always available. Code Assistant (14b) requires 16 GB RAM or 10 GB VRAM. Smart Chat (70b) requires 48 GB RAM or 24 GB VRAM.

Choose what kind of system to build

The profile determines what gets installed on top of the base OS. Four profiles are available:

Desktop — GNOME workstation with ZFS on root. Includes all kldload tools (ksnap, kbe, kdf, kstatus, etc.), the web UI dashboard, Sanoid for automated snapshots, WireGuard, eBPF tools, and the full darksite package cache. This is a complete workstation that happens to run on the most advanced filesystem ever built.

Server — headless SSH server with ZFS on root. Same tools as Desktop minus GNOME. Optimized for remote management. Includes the web UI dashboard on port 8080 for browser-based management.

Core — ZFS on root only. No kldload tools, no web UI, no Sanoid, no darksites. A stock distro installation with the single addition of ZFS as the root filesystem. For users who want ZFS and nothing else.

KVM Host — bare-metal hypervisor. Desktop profile plus libvirt, QEMU/KVM, and the kvm-* toolset for managing VMs on ZFS zvols. Instant clones, atomic snapshots, replication — all at the storage layer.

Target disk, hostname, credentials

The disk selector auto-detects all block devices via lsblk and presents them sorted by priority: NVMe first, then virtio, then SATA/SAS, then USB, and finally the live boot device (flagged with a warning). Each entry shows the device path, size, type (NVMe, SSD, HDD, Virtual), and model string. The first NVMe or virtio disk is auto-selected and marked as recommended. The live boot device is highlighted in amber with a "LIVE BOOT DEVICE — do not install here" warning.

Below the disk selector: hostname (defaults to kldload-node), admin username (defaults to admin), password with real-time strength indicator, password confirmation with match check, and an optional SSH public key textarea for passwordless access.

The ZFS encryption dropdown offers two choices: none (standard ZFS, recommended) or AES-256-GCM with a passphrase. When encryption is selected, two additional fields appear for the ZFS passphrase and confirmation. The UI warns that ZFSBootMenu will prompt for this passphrase on every boot and that there is no recovery mechanism if the passphrase is lost.

Timezone, keyboard, locale

Three dropdowns: timezone (grouped by Americas, Europe, Asia/Pacific, Africa/Middle East — defaults to America/Toronto), keyboard layout (30+ layouts from us to cn — defaults to us), and locale (30+ locales — defaults to en_US.UTF-8). These are passed as KLDLOAD_TIMEZONE, KLDLOAD_KEYBOARD, and KLDLOAD_LOCALE to the installer.

DHCP or static

A checkbox toggles between DHCP (the default) and static network configuration. When static is selected, four fields appear: interface (auto-detected from the system — shows interface name, link state, and current IP), IP address with prefix length, gateway, and DNS servers (comma-separated, defaults to 1.1.1.1,8.8.8.8). The interface dropdown is populated by a network_info WebSocket call that queries all non-loopback interfaces.

Toggle cards for optional features

A 2x2 grid of toggle cards controls optional platform features:

WireGuard — encrypted mesh networking. Enabled by default. Installs WireGuard tools and generates keypairs during bootstrap.

NVIDIA — GPU drivers and CUDA toolkit. Only clickable when an NVIDIA GPU is detected (the card is greyed out and disabled otherwise, based on the has_nvidia flag from lspci output).

eBPF — kernel observability tools. Installs bcc-tools, bpftrace, and kldload's eBPF programs for network and syscall tracing.

ZFS Dedup — block-level deduplication. The card warns "5GB+ RAM per TB" because dedup tables must fit in RAM for reasonable performance.

Build a golden image

A dropdown below the platform options controls image export. The default is "None — install to disk only." When an export format is selected, the installer will build the OS normally, then seal the image for cloning (clear machine-id, remove SSH host keys, enable cloud-init with multi-datasource config), export the ZFS pool, and convert the disk to the chosen format with qemu-img convert.

Available formats: qcow2 (KVM, Proxmox, OpenStack), raw (dd-ready), VHD (Azure, Hyper-V), VMDK (VMware ESXi, vSphere), OVA (VMware, VirtualBox portable).

When a format is selected, SCP export fields appear: remote host, user, path, and SSH password or key path. Leave these blank to save the image locally. Fill them in to have the image automatically uploaded to a remote host after conversion.

The point of no return

Clicking "Install to Disk" opens a confirmation modal with a red warning: "This will permanently erase the selected disk and install kldload." The modal shows the selected disk device, size, and distro. You must click "Yes, erase and install" to proceed. There is also a "Wipe Disk" button that securely zeros the disk for clean re-testing.

Once confirmed, the frontend collects all form values into a JSON payload and sends it as an install action over the WebSocket. The backend writes the answers file, spawns kldload-install-target as a subprocess, and begins streaming its stdout/stderr back to the browser in real-time. A progress bar pulses with a purple glow animation. The install form disappears and the log view takes over.

Real-time log streaming

During installation, you see exactly what is happening. The log display shows every line of output from the installer: partitioning the disk, creating the ZFS pool (rpool), creating datasets (rpool/ROOT/default, rpool/home, rpool/var), running dnf --installroot or debootstrap or pacstrap, installing packages, building ZFS DKMS modules for the target kernel, configuring the bootloader (ZFSBootMenu), setting up the network, applying profile-specific configuration, and running firstboot scripts.

If you refresh the browser mid-install, the web UI detects that an installation is running (via an install_state query) and automatically switches to the install view, resuming the log stream. Nothing is lost.

If the install fails, the progress bar turns red, the error is displayed, and a "Back to installer" button appears so you can fix settings and retry. The backend runs emergency cleanup — unmounting /target and exporting the ZFS pool — so the disk is in a clean state for the next attempt.

Remove the USB and reboot

On success, the progress bar fills to 100% and the status reads "Install complete — system powering off." The installer ejects any optical drives so the machine boots from disk on next start. If this was an unattended install (autoinstall.env present), the system auto-reboots after 10 seconds. Otherwise, it waits for you to remove the USB/ISO and reboot manually with systemctl reboot.

System overview

Six stat cards across the top: Hostname, Uptime, CPUs, Memory (total and free), Network (primary interface, link state, IP address), and AI Chat (if Ollama is installed — shows ready/starting/offline status with a link to Open WebUI). All stats refresh every 5 seconds over the WebSocket.

ZFS pool status

A panel showing the output of zpool status for all imported pools. Pool health, vdev topology, read/write/checksum error counts. If a pool is degraded or faulted, you see it here immediately. Below that, a "Recent Snapshots" panel showing the latest snapshots with timestamps and sizes.

Firstboot progress

On a freshly installed system, a pulsing purple banner appears at the top of the dashboard showing firstboot script progress: "Downloading AI models...", "Configuring WireGuard...", "Building ZFS DKMS...", etc. This status is read from /tmp/kldload-firstboot-status and disappears when firstboot completes.

Pool status

The ZFS view opens with a scrollable panel showing the full output of zpool status. This is the same output you would see in a terminal — pool name, state, scan status (scrub/resilver progress), vdev configuration, and error counts per device. The panel updates on each view switch and can be manually refreshed.

Snapshot management

A table lists all snapshots with columns for name, used space, and actions. The "Take Snapshot" button creates a recursive snapshot of the entire pool with a timestamped name. Each snapshot row has a "Rollback" button that reverts the dataset to that snapshot's state. This calls the same ksnap tooling as the CLI.

Boot environments

A panel showing all boot environments (ZFS datasets under rpool/ROOT/) with the active one highlighted. Two buttons: "New BE" creates a clone of the current boot environment (instant, copy-on-write), and "Refresh" reloads the list. Boot environment switching is done through ZFSBootMenu at the next reboot — the web UI shows you what exists, the bootloader lets you pick which to boot.

Tail anything from the browser

The Logs view has a dropdown to select which log to stream: Installer (/var/log/installer/kldload-installer.log), Firstboot (/var/log/kldload/firstboot.log), or Syslog. Selecting a log sends a read_log action to the backend, which reads the file and returns its contents. During active operations, the tail_log action streams new lines in real-time over the WebSocket.

The backend also supports these log categories via the LOG_FILES registry: storage, network, bootstrap, snapshots, autoboot, and audit. Each maps to a specific file path under /var/log/installer/ or /var/log/kldload/.

KLDLOAD_ environment variables

The answers file is simple: one variable per line, shell-sourceable. The backend writes this file from the web UI form values, or you write it by hand for unattended installs. Every variable has a sensible default. The complete list:

KLDLOAD_DISTRO=centos — target distribution
KLDLOAD_DISK=/dev/vda — target block device
KLDLOAD_PROFILE=server — desktop, server, core, or kvm
KLDLOAD_HOSTNAME=kldload — system hostname
KLDLOAD_USERNAME=admin — admin user account name
KLDLOAD_PASSWORD=... — admin password (hashed or plain)
KLDLOAD_NET_METHOD=dhcp — dhcp or static
KLDLOAD_NET_IFACE=eth0 — network interface (static only)
KLDLOAD_NET_IP=192.168.1.100 — IP address (static only)
KLDLOAD_NET_PREFIX=24 — CIDR prefix (static only)
KLDLOAD_NET_GW=192.168.1.1 — gateway (static only)
KLDLOAD_NET_DNS=1.1.1.1,8.8.8.8 — DNS servers
KLDLOAD_STORAGE_MODE=zfs — storage mode
KLDLOAD_ZFS_TOPOLOGY=single — single, mirror, raidz, stripe
KLDLOAD_ZFS_ENCRYPT=0 — 0 or 1
KLDLOAD_WIREGUARD=0 — 0 or 1
KLDLOAD_NVIDIA_DRIVERS=0 — 0 or 1
KLDLOAD_ENABLE_EBPF=0 — 0 or 1
KLDLOAD_ENABLE_AI=0 — 0 or 1
KLDLOAD_EXPORT_FORMAT=none — none, qcow2, raw, vhd, vmdk, ova
KLDLOAD_EXPORT_SCP_HOST=... — remote host for image upload
KLDLOAD_EXPORT_SCP_USER=root — remote user
KLDLOAD_EXPORT_SCP_PATH=/root/ — remote path
KLDLOAD_INFRA_MODE=standalone — standalone or cluster
KLDLOAD_DEBIAN_RELEASE=trixie — Debian codename

Three lines of Python

You can drive an installation from any language that speaks WebSocket. Here is the minimal Python example:

import asyncio, websockets, json

async def install():
  async with websockets.connect("ws://192.168.1.50:8080") as ws:
    await ws.send(json.dumps({
      "action": "install",
      "distro": "centos",
      "disk": "/dev/vda",
      "hostname": "prod-web-01",
      "password": "changeme",
      "profile": "server"
    }))
    async for msg in ws:
      data = json.loads(msg)
      if data["type"] == "install_log":
        print(data["line"], end="")
      elif data["type"] == "install_state":
        if data.get("rc") == 0:
          print("Install complete")
          break

asyncio.run(install())

That's it. Connect, send, stream. The same pattern works for any action — replace the action name and payload, parse the response type.

File locations

Backend: /usr/local/bin/kldload-webui — the Python WebSocket server. Runs as a systemd service. Edit this to add new API actions, change behavior, or integrate with external tools.

Frontend (free edition): /usr/local/share/kldload-webui/free/index.html — the full installer and dashboard with all features.

Frontend (core edition): /usr/local/share/kldload-webui/core/index.html — a stripped-down UI with only the install wizard and basic ZFS management. No cluster designer, no service management, no advanced options.

CSS: /usr/local/share/kldload-webui/css/app.css — the stylesheet. Dark theme by default. All colors use CSS custom properties so you can retheme with a handful of variable overrides.

Active edition: /usr/local/share/kldload-webui/active/ — symlinked or copied at build time. This is what the backend actually serves.

Adding a custom field to the installer

To add a new option to the install form:

1. Add the HTML form element to index.html inside the #install-idle div.

2. In the startInstall() JavaScript function, read the value and include it in the JSON payload sent to the WebSocket.

3. In kldload-webui, find the install action handler. The backend writes the answers file from the received JSON — add your new field as a KLDLOAD_ variable.

4. In kldload-install-target or the appropriate library file, read the new variable and act on it during installation.

That's the entire chain: HTML form → JavaScript → WebSocket JSON → Python → answers file → bash installer. Four files, four edits, zero framework magic.

Design multi-node infrastructure in the browser

The state database supports cluster definitions — collections of nodes with assigned roles, WireGuard mesh configurations, and service deployments. The cluster_save and cluster_deploy API actions let you define a cluster topology in JSON and push it to target nodes. Each node registers itself via db_node_register with its hostname, management IP, WireGuard public keys, and system facts.

The cluster designer stores everything in the SQLite state database. Templates can be exported as JSON (db_export) and imported on another node (db_import) for live-to-master handoff — design the cluster on one machine, export the state, import it on the actual infrastructure.

Define, deploy, and track services

Services are defined with a name, description, runtime (systemd, container, etc.), target nodes, ZFS dataset, container image, replica count, replication targets, and custom config. Each service gets its own ZFS dataset at rpool/services/{name} by default. The service_deploy action pushes the service definition to target nodes and starts it. Service status is tracked in the state database.

Stored secrets

The web UI can store credentials at /run/kldload/credentials.json (in tmpfs, not persisted to disk) for services that need authentication: Red Hat portal, SCP targets, WireGuard endpoints. The credentials_save, credentials_load, and credentials_test actions manage these. Credentials stored in /run/ disappear on reboot — this is intentional for security on live ISOs.

KVM virtual machines on ZFS

On KVM Host profile installations, the API exposes VM lifecycle actions: spawn creates a new VM on a ZFS zvol, list_vms shows all defined VMs, vm_op handles start/stop/destroy/snapshot, and vm_clone creates instant ZFS clones of existing VMs. The vm_replace action destroys a VM and recreates it from its golden image — immutable infrastructure at the hypervisor level.

Sidebar navigation

A narrow sidebar on the left with the kldload logo at the top. Four navigation items: Dashboard (diamond icon), Install to Disk (lightning bolt icon), ZFS & Snapshots (half-filled square icon), and Logs (three-line icon). The sidebar has section headers for System, Install, Storage, and Tools. A small status indicator at the top of the main content area shows a colored dot (green for connected, red for disconnected) and connection text.

Dashboard screen

A release banner at the top with a gradient border (green to purple) showing the current version and changelog highlights. Below that, a grid of six stat cards in a row: hostname in large text, uptime in green, CPU count, memory with free amount, network interface with link state and IP, and AI status (if enabled). Two panels below: ZFS Pools showing a one-line pool summary, and Recent Snapshots showing the latest snapshot names and timestamps.

Install screen

A vertical flow of panels, each with a dark header bar. The distro grid is a 9-column row of cards, each with an emoji icon, distro name, and "offline" or "internet required" label. Selected cards have a green border. Below: the AI assistant toggle card with a large brain emoji, description text, CLI tool reference in a monospace box, hardware requirements, and a toggle switch. Then the profile grid (4 cards: Desktop, Server, Core, KVM Host). Then the disk/identity panel with a dropdown, text inputs, password fields with strength indicators. Then localisation with three dropdowns. Then network with a DHCP checkbox and collapsible static fields. Then platform options as four toggle cards in a 2x2 grid. Finally, the export format dropdown with optional SCP fields. At the bottom, a green "Install to Disk" button and a red "Wipe Disk" button.

Install progress screen

Replaces the install form when installation starts. A header reads "Installing — do not power off." A one-line summary shows the selected distro and profile in monospace. A thin progress bar with a pulsing purple glow animation. A status line in grey text. Below that, a large scrollable log box (340px tall) with monospace text showing real-time installer output — each line appears as the backend streams it. If the install fails, the bar turns red and a "Back to installer" button appears.

ZFS screen

Three panels stacked vertically. Pool Status: a scrollable monospace box showing full zpool status output. Snapshots: a table with Name, Used, and Actions columns, plus a purple "Take Snapshot" button in the panel header. Boot Environments: a scrollable monospace box showing BE names and active markers, with "New BE" and "Refresh" ghost buttons below.

Logs screen

A single panel with a dropdown selector in the header (Installer, Firstboot, Syslog). Below, a large scrollable monospace log box (380px tall) that fills with the selected log content. During active operations, new lines scroll into view automatically.

Confirm modal

A centered modal overlay with a dark semi-transparent background. The modal box has a red warning header "Erase disk and install?", explanatory text, a detail section showing the selected disk and configuration, and two buttons: grey "Cancel" and red "Yes, erase and install." The modal blocks all interaction until dismissed.