Halo Server configuration
Halo Server configuration reference: environment variables for server mode, port, data directory, access password and your own LLM gateway.
Halo Server is configured entirely through environment variables. A variable that is set wins; anything unset keeps the saved configuration or the built-in default.
Environment variables
| Variable | Purpose | Default |
|---|---|---|
HALO_SERVER_MODE | Starts Halo in headless server mode when set to 1 or true | Unset means desktop mode; the image sets it to 1 |
PORT | HTTP listen port | 8080 |
HALO_SERVER_PORT | Listen port used when PORT is not set | — |
HALO_DATA_DIR | Data directory. Mount a persistent volume here in production | /tmp/.halo (temporary, wiped) |
HALO_REMOTE_PASSWORD | Access password, sent as Authorization: Bearer when calling the API | halo123, only if no password was ever saved; change it |
HALO_AI_PROVIDER | Model protocol family: anthropic, openai, custom and others | anthropic |
HALO_AI_API_URL | Model endpoint: your own model gateway | https://api.anthropic.com |
HALO_AI_API_KEY | Key for the model gateway | — |
HALO_AI_MODEL | Model name | A built-in Claude model |
The four HALO_AI_* variables take effect only when HALO_AI_API_KEY or HALO_AI_API_URL is set, and then they replace the model sources Halo already has. With neither set, Halo keeps the model sources configured in the app.
Data persistence
All of Halo Server's state (the SQLite database, workspace data and files) is written under HALO_DATA_DIR. With HALO_DATA_DIR set, the image built from deploy/server also keeps global skills, the AI engine's conversation records and the built-in browser profile in $HALO_DATA_DIR/home, so they persist as well.
The default /tmp/.halo is a temporary directory: its data is wiped when the instance recycles, restarts or scales to zero.
Mount a persistent volume in production
Point HALO_DATA_DIR at a mounted persistent volume (usually NFS). Otherwise every instance recycle loses all data.
HALO_DATA_DIR=/dataThen mount the volume at /data at the platform or Docker layer, as shown in Deploy with Docker and Serverless deployment.
SQLite on NFS
SQLite on NFS usually works for a single writer, which is exactly what Halo Server is: one instance, one writer. NFS file locking differs between vendors, though, so test writes, concurrent reads and restart recovery in your storage before going live. It is also why you cannot scale out: several instances writing the same SQLite file corrupt it.
Access password
HALO_REMOTE_PASSWORD is the credential for calling the Halo Server API, sent as a bearer token:
Authorization: Bearer <YOUR_ACCESS_PASSWORD>Replace <YOUR_ACCESS_PASSWORD> with the password you set.
The access password is an admin password
The access password grants full control of this Halo Server, including its files, terminal and AI. Set a random password of 8–64 characters: the sign-in page does not accept fewer than 8, so the default halo123 cannot even sign in to the web app. Do not rely on the default, and never put the password in web pages, repositories or logs.
Generate a random 48-character password:
openssl rand -hex 24HALO_REMOTE_PASSWORD applies on every start. When it is not set, Halo keeps the password it saved last time, and uses halo123 only if none was ever saved.
LLM configuration
Halo ships without a model. Each deployment connects its own model endpoint and key: a self-hosted inference service or your organization's model gateway.
HALO_AI_PROVIDER=openai
HALO_AI_API_URL=https://ai-gateway.example.com/v1
HALO_AI_API_KEY=<YOUR_API_KEY>
HALO_AI_MODEL=<MODEL_NAME>HALO_AI_PROVIDERpicks the protocol family (Anthropic, OpenAI-compatible or custom).HALO_AI_API_URLpoints at your own model gateway, so traffic can stay inside your network.HALO_AI_API_KEYis the key for that gateway; replace<YOUR_API_KEY>with the real key.HALO_AI_MODELis the model to call; replace<MODEL_NAME>with a model your gateway offers.
Example .env
# Run mode
HALO_SERVER_MODE=1
PORT=8080
# Persistence: must point at a mounted volume in production
HALO_DATA_DIR=/data
# Access password: 8-64 random characters, for example the output of openssl rand -hex 24
HALO_REMOTE_PASSWORD=<YOUR_ACCESS_PASSWORD>
# LLM (your own gateway)
HALO_AI_PROVIDER=openai
HALO_AI_API_URL=https://ai-gateway.example.com/v1
HALO_AI_API_KEY=<YOUR_API_KEY>
HALO_AI_MODEL=<MODEL_NAME>Related
- Deploy with Docker: run the container with these variables
- Serverless deployment: set these variables on a function platform
- HTTP API overview: call the API with the access password