Config schema reference

The runtime config lives at /etc/hal0/hal0.toml. The schema is defined in Pydantic (src/hal0/config/schema.py) and exported as JSON Schema for clients that want machine-readable references.

How the schema is enforced

Every read of hal0.toml goes through pydantic.model_validate. A failed validation raises a structured config.invalid error with details.path pointing at the offending field. The dashboard surfaces this inline; the CLI prints it with the same code.

hal0 config validate runs the schema check without writing anything — safe to run at any time.

Top-level sections

Section	Purpose
[api]	API listen host/port, request limits, telemetry toggle.
[paths]	FHS path overrides for unusual deployments.
[slots.<name>]	One block per slot — see below.
[upstreams]	External OpenAI-compatible providers (optional).
[update]	Update channel + cosign signer identity.
[openwebui]	Bundled UI configuration knobs.

Per-slot block

Every slot entry has at minimum:

[slots.primary]
provider = "llama.cpp"                       # one of: llama.cpp, flm, moonshine, kokoro
model = "qwen2.5-0.5b-instruct-q4_k_m"       # registry ref
port = 8081                                  # 8081-8099, must be unique
idle_timeout_seconds = 600                   # ready -> idle transition threshold

Provider-specific knobs go under [slots.<name>.options]. The four built-in slots (primary, embed, stt, tts) cannot be removed; their provider, model, and port fields are still freely editable.

Defaults & FHS paths

Defaults match the FHS layout (PLAN §2):

Path	Default
Install root	/usr/lib/hal0/current/
Config dir	/etc/hal0/
State dir	/var/lib/hal0/
Model registry	/var/lib/hal0/models/
Per-slot state file	/var/lib/hal0/slots/<name>/state.json
OpenWebUI state	/var/lib/hal0/openwebui/

HAL0_HOME overrides all of the above as a single root — useful for dev installs that don’t want to touch system dirs.

Atomic writes

Every config write goes through the NamedTemporaryFile → fsync → os.replace() pattern. A failed write leaves the previous file intact. The same pattern applies to per-slot env files at /etc/hal0/slots/<name>.env.

Hardware probe sidecar

/etc/hal0/hardware.json is not part of hal0.toml — it’s probe output, regenerated by hal0 probe, consumed by the slot loader. Don’t hand-edit it.

Note

The canonical, always-current schema is the Pydantic model in the repo. This page summarises what’s there; if you need the exhaustive field list, the JSON Schema export is the source of truth.

Coming soon — outline

• Embedded JSON Schema dump on this page, generated from the Pydantic model at build time.
• Per-field anchor links for direct deep-linking from error messages.
• Drop-in fragment support — /etc/hal0/conf.d/*.toml merged on load.