Install on bare metal

Docs Start here
1

Bare metal is the simplest way to run hal0: the installer handles the
container runtime and Python venv for you, and on a Strix Halo box the
iGPU and NPU are already present as local device nodes — no passthrough to
configure. This guide covers a clean Ubuntu 24.04+ or Debian 13 x86_64 host.

Note: Linux + systemd only

hal0 v1 targets Linux x86_64 with systemd. That is the only hard
platform requirement — ARM, macOS, and Windows are out of scope. (For
Windows, see the WSL2 quick start, but note
it is experimental.)

1. Prerequisites

The installer’s pre-flight verifies each of these and installs what it can:

Requirement Notes
x86_64 / amd64 Hard requirement — the toolbox images and FastFlowLM .deb are amd64-only.
systemd systemctl must be on PATH. Pre-flight fails hard without it.
Ubuntu 24.04+ or Debian 13 Stock Debian 12 and Ubuntu 22.04 ship Python 3.11, which fails the installer’s Python ≥ 3.12 preflight. On those releases, either point at a newer interpreter with HAL0_PYTHON=python3.12, or set HAL0_PY_AUTOINSTALL=1 to let the installer provision one.
Python ≥ 3.12 pip install of the release tree hard-requires 3.12+. Missing Python is fatal.
python3-venv + pip The Ubuntu base ships python3 without ensurepip; the installer auto-installs these on apt.
A container runtime Auto-installs podman if none is found.
~20 GB free disk Under /var/lib, plus free ports 8080 (API) and 3001 (OpenWebUI).

Install the venv prerequisite up front so the first run is clean:

sudo apt-get update && sudo apt-get install -y python3-venv python3-pip

2. GPU drivers and GTT sizing

Before installing on GPU hardware, make sure the host kernel already
exposes the iGPU (and NPU, if present) as device nodes — hal0 ships the
ROCm/XRT userspace inside its containers, but it cannot load a kernel
driver from inside one. See the Kernel and firmware section of
GPU drivers and memory
for the kernel/firmware requirements and verification steps.

On a Strix Halo box, also size the amdgpu GTT pool on the host kernel
command line before you install — see the Size the GTT pool section of
GPU drivers and memory for
the reference grub parameters.

3. Install hal0

curl -fsSL https://hal0.dev/install.sh | sudo bash

The bootstrap fetches the release manifest, SHA-256- and cosign-verifies
the tarball, then hands off to the installer, which installs podman, builds
the venv, writes systemd units, runs a hardware-recommended first-run
setup, and starts hal0-api on port 8080. See Install hal0
for the full sequence and every environment variable and flag.

Tip: GPU device groups

On a GPU host the installer adds the hal0 service user to the render
and video groups so slot containers can open /dev/kfd and
/dev/dri/renderD*. See the Render-group gids section of
GPU drivers and memory if
you need to hand-wire device access (e.g. in an LXC).

4. Verify

hal0 status
hal0 slot list
curl http://localhost:8080/api/health
journalctl -fu hal0-api

hal0 status reports system + slot + memory health; hal0 slot list
shows configured slots; the /api/health curl is a lightweight liveness
probe (200 the moment the API is serving); journalctl -fu hal0-api
tails the control-plane log if something looks wrong. The dashboard is at
http://localhost:8080; OpenWebUI at :3001.

5. (Optional) Enable the NPU

If the host has an AMD XDNA NPU and the amdxdna kernel driver is loaded
(kernel ≥ 6.11, NPU firmware ≥ 1.1.0.0, /dev/accel/accel0 present), the
installer auto-installs the FastFlowLM (FLM) userspace on apt hosts.
Verify with:

flm validate       # → "flm validate ok — NPU runtime reachable"

A single flm serve process backs the NPU trio — a chat model plus
opt-in embedding and speech-to-text passengers on the seeded npu slot
(port 8088). On non-apt distros the NPU path is skipped and you install
FastFlowLM manually; the GPU and CPU paths are unaffected.

Next

Your first slot
Hal0 documentation
Hal0 docs: Start here
hal0 documentation index