Install on bare metal

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.

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 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 Size the GTT pool 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.

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 Render-group gids 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

Load your first modelPull a model from Hugging Face and assign it to a slot.

Send your first chatChat from OpenWebUI or curl the OpenAI-compatible endpoint.

Install on ProxmoxThe unprivileged quick-start script, plus GPU/NPU passthrough for Strix Halo.

GPU drivers and memoryKernel driver requirements, device nodes, and GTT sizing in depth.