Install

hal0 installs in one line on any modern Linux box. The installer detects your hardware, picks the right backend (Vulkan, ROCm, CUDA, or CPU), writes a systemd unit, and brings up the API plus a prewired chat UI.

The one-liner

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

After the installer finishes you’ll have:

• API at http://localhost:8080 — OpenAI-compatible /v1/*
• Dashboard at http://localhost:8080 (same port, served by the API)
• OpenWebUI at http://localhost:3001 — prewired to the local API

The installer is idempotent. Re-running it never clobbers your existing config in /etc/hal0/.

What runs as root

The installer needs sudo to drop systemd unit files into /etc/systemd/system/ and create the /usr/lib/hal0/ tree. The hal0-api service itself runs as the unprivileged hal0 user.

Prerequisites

1. Linux with systemd. Tested on Arch, CachyOS, Fedora, Ubuntu 22.04+. macOS and Windows are not in scope for v1.

2. x86_64. ARM is not currently supported.

3. Docker accessible. The slot toolboxes run as containers. The installer checks docker ps before doing anything destructive.

4. At least 20 GB free in /var/lib. Models and OpenWebUI state land there.

5. Ports 8080 and 3001 free. Override with HAL0_PORT and HAL0_OPENWEBUI_PORT if you need different ones.

What the installer does

1. Pre-flight checks. Verifies systemd, x86_64, Docker, free space, and free ports. Bails before touching anything if a check fails.

2. Hardware probe. Detects GPU, NPU, and unified memory pools. Writes /etc/hal0/hardware.json. The result picks default backends for the four built-in slots and feeds the slot-fit warnings in the dashboard.

3. Layout. Creates the FHS-aligned tree:

   • /usr/lib/hal0/current/ — versioned code, atomic symlink
   • /etc/hal0/ — config (hal0.toml, api.env, openwebui.env, slot skeletons), preserved across updates
   • /var/lib/hal0/ — models, registry, OpenWebUI state

4. Config defaults. Writes hal0.toml plus the four built-in slot skeletons (primary, embed, stt, tts). Existing files are never overwritten on re-run.

5. systemd units. Drops hal0-api.service, hal0-openwebui.service, and the hal0-slot@.service template into /etc/systemd/system/. Reloads the daemon, enables and starts the API plus OpenWebUI.

6. Ready. Prints the URLs and points you at the first-run wizard.

Overrides

Every knob is an environment variable. Pass them on the same line as the installer:

HAL0_PORT=9090 HAL0_OPENWEBUI_PORT=9091 \
  curl -fsSL https://hal0.dev/install | bash

Variable	Default	Purpose
HAL0_PREFIX	/usr/lib/hal0	Install prefix
HAL0_PORT	8080	API + dashboard port
HAL0_OPENWEBUI_PORT	3001	OpenWebUI port
HAL0_USER	hal0	Service user
HAL0_PYTHON	python3	Python interpreter
HAL0_NO_PROBE	unset	Skip the hardware probe
HAL0_AUTO_PULL	0	Pre-pull toolbox images on install
HAL0_TOOLBOX_IMAGE_VULKAN	repo default	Override Vulkan toolbox tag
HAL0_TOOLBOX_IMAGE_ROCM	repo default	Override ROCm toolbox tag

For dev installs, set HAL0_HOME=$PWD/.hal0 to relocate the whole tree under your working directory and skip the systemd path entirely.

Authentication & HTTPS (optional)

The default install has no auth in front — fine on a trusted home LAN, not safe on the open internet. To enable Caddy + basic_auth + bearer tokens + automatic HTTPS, add --auth=basic:

sudo bash installer/install.sh --auth=basic

The installer prompts for an admin user/password, installs Caddy, generates a TLS cert (self-signed for .local hostnames, Let’s Encrypt for real domains), and brings the dashboard up at https://hal0.local/. See Authentication & HTTPS for the full flow, client-side cert trust, and ACME setup.

From a clone

If you already have the repo and want to test changes locally:

git clone https://github.com/hal0ai/hal0
cd hal0
sudo bash installer/install.sh

The script in the repo is the same one the URL serves.

Verifying the install

hal0 status

Prints a system summary plus the state of every slot. If hal0-api is healthy you’ll see the four built-in slots in the offline state — the first-run wizard lights up primary for you.

curl http://localhost:8080/v1/models

Returns an empty data: [] until you’ve assigned a model to a slot.

Next steps

Load your first model The three-step FirstRun wizard: pick model, accept license, download.

Send your first chat OpenWebUI is prewired. Open it and start talking.

Strix Halo notes The reference platform — unified memory iGPU, NPU, the tuning details.

Hardware overview Where hal0 runs best and the supported tiers.

Uninstalling

sudo bash /usr/lib/hal0/current/installer/uninstall.sh

Stops the services, removes the unit files, and (with --keep-data) leaves your config and models in place. Without --keep-data it also clears /etc/hal0 and /var/lib/hal0.

hal0 uninstall (CLI) not yet implemented

hal0 uninstall is staged but returns NOT_IMPLEMENTED in the current build. Use the bundled uninstall.sh directly. See the CLI reference for the implementation status of every subcommand.