Environment variables reference

There is no single global HAL0_* → config-key mapping. Each variable below is read by name at a specific call site. Most have a hardcoded fallback if unset.

Install layout

Variable	Default	Controls
HAL0_HOME	unset (production FHS paths)	Overrides all root paths for dev installs/tests: usr_lib, lib, etc, var_lib, var_log. See Paths & files.
HAL0_PREFIX	unset → $PWD/.hal0ai	Dev-prefix install root override, used by hal0 uninstall --dev.
HAL0_FHS_ROOT	unset → usr_lib()	FHS release-tree root override for hal0 doctor’s preflight-script lookup.
HAL0_PREFLIGHT_SH	unset (auto-discovered)	Explicit override path to preflight.sh.
HAL0_FORCE	unset	HAL0_FORCE=1 skips the hal0 uninstall --purge confirmation prompt.
HAL0_ALLOW_ROOT	unset (false)	1/true/yes allows the hal0-agent shim to run as root.
HAL0_AGENTS_CONF_DIR	/etc/hal0/agents	—

Model / storage

Variable	Default	Controls
HAL0_MODEL_STORE	unset	Overrides the model-store root. Precedence: env → [models].store/effective_store() in hal0.toml → /var/lib/hal0/models.
HAL0_FLM_MODELS_DIR	unset	NPU/FLM model-store dir override. Precedence: env → [models].flm_store → /var/lib/hal0/.config/flm/models.

API / networking

Variable	Default	Controls
HAL0_PORT	8080	API port. Also read by hal0 serve --port.
HAL0_BIND_HOST	0.0.0.0	API bind host. Also read by hal0 serve --host.
HAL0_HOSTNAME	socket.gethostname()	Canonical hostname override.
HAL0_PUBLIC_URL	unset	Public URL announced by the installer/mDNS.
HAL0_LAN_IPS	""	—
HAL0_SELF_BASE_URL	http://127.0.0.1:8080	Self-referential base URL used by the realtime backend and internal API calls.
HAL0_UI_DIST	"" (built-in dist dir)	Override the served UI static-asset directory.
HAL0_REQUIRE_AUTH	unset	Overrides [security].require_auth — wins over the persisted config value.
HAL0_TRUST_FORWARDED_FOR	unset	Overrides [security].trust_forwarded_for — wins over the persisted config value.
HAL0_ALLOWED_ORIGINS	"" (falls back to a built-in default set)	Comma-separated CORS allowlist for the agent chat WebSocket.
HAL0_MCP_ALLOWED_HOSTS	""	—
HAL0_MCP_ALLOWED_ORIGINS	""	—
HAL0_ADMIN_KEY	minted on rotation, else read from api.env	Admin bearer key for /api/*. See hal0 auth.
HAL0_CLIENT_KEY	minted on rotation, else read from api.env	Client bearer key.
HAL0_OPENROUTER_OAUTH_ENABLED	unset (disabled)	1/true enables OpenRouter OAuth.
HAL0_COMFYUI_PUBLIC_URL	""	—
HAL0_OPENWEBUI_PUBLIC_URL	""	—
HAL0_OPENWEBUI_PROBE_URL	""	—
HAL0_HERMES_PUBLIC_URL	""	—
HAL0_API_URL	http://127.0.0.1:8080 (CLI client default)	Base URL the CLI uses to reach hal0-api.

Caution

HAL0_API_URL’s embedded default differs by call site: the CLI shared HTTP helper (cli/_shared.py) defaults to http://127.0.0.1:8080, while some agent-provisioning code paths (agents/hermes_provision.py) default to http://hal0.local:8080. If you rely on the default rather than setting it explicitly, verify which code path applies.

Hermes agent

Variable	Default	Controls
HAL0_HERMES_RUNTIME_JSON	/var/lib/hal0/.hermes/runtime.json	Hermes runtime info file (embed token etc).
HAL0_HERMES_HOST	127.0.0.1	—
HAL0_HERMES_PORT	9119	—
HAL0_HERMES_PYTHON	unset (auto-discovered interpreter)	—
HAL0_HERMES_LIVE_RESOLVE	"1"	—
HAL0_HERMES_OFFLINE	unset	Set programmatically by hal0 agent bootstrap --offline.
HAL0_AGENTENV	/usr/lib/hal0/bin/hal0-agentenv	—
HAL0_SYSTEMCTL	/usr/lib/hal0/bin/hal0-systemctl	—
HAL0_INFERENCE_BASE	http://127.0.0.1:8080	—
HAL0_AGENT_SECRET_PATH	/var/lib/hal0/agents/secret.bin	HMAC session-cookie secret for the agent chat proxy.
HAL0_AGENT_ID	varies by call site ("hermes" in board/manifest-proxy code, a module constant elsewhere)	—
HERMES_HOME	~/.hermes	—
HERMES_SESSION_TOKEN	unset	—
HERMES_DASHBOARD_BASE_URL	module-local default constant (grep board/hermes_executor.py for the exact literal)	—

Hindsight memory

Variable	Default	Controls
HAL0_MEMORY_BASE	module-local default constant	Base URL for the memory-plugin client.
HAL0_MEMORY_DEFAULT_VISIBILITY	module-local default constant	—
HAL0_MEMORY_SPOOL	unset	—
HAL0_HINDSIGHT_URL	http://127.0.0.1:9177	Hindsight engine base URL.
HAL0_HINDSIGHT_PROBE_TIMEOUT_S	—	Probe timeout for the Hindsight health check.
HINDSIGHT_API_TENANT_API_KEY	hal0-local-noauth	—

Providers / external services

Variable	Default	Controls
HF_TOKEN, HUGGING_FACE_HUB_TOKEN	unset (first-set wins)	Hugging Face Hub auth, used across install, model routes, and pull jobs.
COMFYUI_BASE_URL	http://127.0.0.1:8188	—
COMFYUI_CONTAINER	comfyui	—
COMFYUI_MODELS_DIR	/mnt/ai-models/comfyui/models	—
COMFYUI_WORKFLOWS_DIR	/mnt/ai-models/comfyui/workflows	—
COMFYUI_DATA_DIR	/mnt/ai-models/comfyui	—
HAL0_COMFYUI_DATA_ROOT	""	—
HAL0_CONTAINER_RUNTIME	unset (auto-detect)	Overrides the podman/container runtime binary.
HAL0_FLM_BIN	/usr/bin/flm	—
HAL0_FLM_HOME	/var/lib/hal0	—
HAL0_FLM_USER	hal0	—
HAL0_FLM_BINARY	{native_flm_root}/bin/flm	—
HAL0_QWEN3TTS_CACHE	module-local default constant	—
HAL0_AVAHI_SERVICES_DIR	""	—
HAL0_HOST_RAM_GB	"" (auto-probe)	—
HAL0_BUNDLES_DIR	""	—

Activity / metrics / bench

Variable	Default	Controls
HAL0_ACTIVITY_RETENTION_DAYS	falls back to [activity].retention_days	—
HAL0_BENCH_SUITE_DIR	unset	—
HAL0_BENCH_API	module-local default constant	—
HAL0_BENCH_STATE	/var/lib/hal0-bench ($HAL0_HOME/var-lib/hal0-bench under HAL0_HOME)	—
HAL0_BENCH_HOST, HAL0_BENCH_PLATFORM, HAL0_BENCH_GPU, HAL0_BENCH_HAL0_VERSION	probed values	Override the identity fields hal0 bench records with a run.

Misc

Variable	Default	Controls
HAL0_SETUP_TIMEOUT_SECS	300.0	Timeout for hal0 setup’s non-interactive install steps.
HAL0_FORCE_INTERACTIVE	unset	Forces hal0 setup into interactive mode even in a non-TTY.
NO_COLOR, HAL0_PLAIN	unset	Disable ANSI color / force ASCII-only output.
EDITOR, VISUAL	vi	Editor used by hal0 config edit.
NOTIFY_SOCKET	inherited from systemd	sd_notify socket — not hal0-specific.

Note

.bundle-chosen-related bundle-tier env vars (HAL0_HOST_RAM_GB, HAL0_BUNDLES_DIR) back a bundle picker that is explicitly unwired/deferred past v1.0 — don’t imply it’s an active operator-facing flow.