Documentation
Configuration
Halo reads its configuration from environment variables when a halo command starts. If a required variable is missing or invalid, the command lists every problem and exits without starting, for example:
halo: configuration is incomplete:
HALO_SECRET_KEY must be 32 random bytes, base64 encoded. Generate one with: openssl rand -base64 32
Server
The Go server (halo serve and the other halo commands) reads these variables.
| Variable | Required | Default | Example |
|---|---|---|---|
HALO_PUBLIC_URL |
Yes | https://auth.example.com |
|
HALO_DATABASE_URL |
Yes | postgres://halo:secret@postgres:5432/halo |
|
HALO_SECRET_KEY |
Yes | Output of openssl rand -base64 32 |
|
HALO_LISTEN |
No | :8080 |
127.0.0.1:8080 |
HALO_ORGANIZATION |
No | Halo |
Fernway Systems |
HALO_DEV |
No | Off | 1 |
HALO_TRUSTED_PROXIES |
No | 127.0.0.1/32,::1/128 |
172.31.250.0/24 |
HALO_DISABLE_CUSTOM_CSS |
No | Off | 1 |
HALO_SMTP_HOST |
No | smtp.example.com |
|
HALO_SMTP_PORT |
No | 587 |
465 |
HALO_SMTP_USERNAME |
No | halo@example.com |
|
HALO_SMTP_PASSWORD |
No | ||
HALO_SMTP_FROM |
When HALO_SMTP_HOST is set |
Halo <halo@example.com> |
HALO_PUBLIC_URL
The address people type to reach Halo: the web interface, not the Go server. Halo uses it in three ways:
- It is the OpenID Connect issuer. Applications must use exactly this value, and it appears as
issin every token. - Its hostname is the passkey (WebAuthn) relying party ID. Passkeys only work on the hostname they were created for, so changing the hostname later means everyone needs a new passkey.
- Its origin is the only one the same-origin check accepts.
It must be an absolute URL, and it must use https unless HALO_DEV=1. Halo removes a trailing slash.
HALO_DATABASE_URL
The PostgreSQL connection URL. Halo is developed and tested against PostgreSQL 17. Every halo command applies pending migrations when it connects, so halo serve upgrades the schema on start; halo migrate applies migrations and exits.
HALO_SECRET_KEY
32 random bytes, base64 encoded with the standard alphabet. Generate one with openssl rand -base64 32.
Halo encrypts these with this key using AES-256-GCM: the OpenID Connect and SAML signing keys, the SSH certificate authority's key, authenticator-app secrets, identity provider client secrets, webhook signing secrets, the tokens Halo uses to provision applications over SCIM, and email waiting in the outbox. It also derives from it the key that encrypts opaque access tokens and authorization codes, and the key that recovery codes are hashed with (HMAC-SHA256). Starting Halo with a different key without rotating makes those values unreadable, so nobody can sign in to applications and authenticator-app codes stop working until the original key is back. Back it up together with the database.
To replace the key, stop Halo and run halo rotate-secret-key with the current key in HALO_SECRET_KEY and the new one in HALO_NEW_SECRET_KEY. It re-encrypts every stored secret in one transaction and removes recovery codes, which cannot be re-derived, then prints what to change in your deployment. Rotate HALO_SECRET_KEY walks through it.
HALO_LISTEN
The address the Go server listens on, as host:port or :port.
HALO_ORGANIZATION
Your organization's name, shown in the console, on the sign-in page and in email. A global administrator can override it in the console under Organization; this variable is the name Halo uses while that setting is empty. The API returns the name in use from GET /api/v1/organization.
HALO_DEV
Development mode. It is on only when the value is exactly 1. Development mode:
- allows
HALO_PUBLIC_URLto use plain http, - removes the Secure flag from Halo's cookies,
- lets the OpenID Connect provider run on plain http,
- enables
halo seed-demoandhalo dev-session, - adds
GET /api/v1/dev/outbox, which shows global administrators the 50 most recent emails, - accepts
http://localhostandhttp://127.0.0.1as identity provider issuers.
Never set it in production.
HALO_TRUSTED_PROXIES
A comma-separated list of CIDR ranges, such as 10.0.0.0/8,172.31.250.0/24, for the reverse proxies in front of the Go server. Halo refuses to start if an entry is not a valid CIDR range. The default trusts only the local machine.
Halo records a client IP address on every sign-in, session and audit event. When a request arrives from an address in these ranges, Halo reads X-Forwarded-For from right to left and uses the first address that is not itself in these ranges. Requests from any other address use the connecting address and ignore the header, so a client cannot forge its own address.
In the Docker Compose deployment, the Go server sits behind the web container, so set this to the subnet of the Compose network: 172.31.250.0/24 in the provided files. Without it, Halo records the web container's address for everyone.
HALO_DISABLE_CUSTOM_CSS
Turns off the custom CSS on every page when the value is exactly 1. Use it to recover from a stylesheet that broke the sign-in page: start Halo with the variable set, open Branding in the console, fix the CSS, then remove the variable and restart Halo. The Branding page says the variable is set, GET /api/v1/organization returns an empty customCss while it is, and GET /api/v1/settings returns customCssDisabled: true. The saved CSS is kept.
SMTP
HALO_SMTP_HOST, HALO_SMTP_PORT, HALO_SMTP_USERNAME, HALO_SMTP_PASSWORD and HALO_SMTP_FROM describe the mail server Halo sends email through. Email is configured when HALO_SMTP_HOST is set, and then HALO_SMTP_FROM is required.
Halo emails invite links, reset links, magic sign-in links and access request notices. Every message goes into an outbox in the database first; Halo retries failed deliveries with growing gaps, up to 5 attempts within a day. Without SMTP, messages are queued but not sent, and administrators pass invite and reset links on themselves. Email explains the outbox and magic links.
- Port
465uses TLS from the start of the connection. On any other port, Halo requires STARTTLS, except when the host islocalhostor a loopback address. - With
HALO_SMTP_USERNAMEset, Halo authenticates with PLAIN usingHALO_SMTP_USERNAMEandHALO_SMTP_PASSWORD.
Web interface
The Next.js web interface reads these variables.
| Variable | Default | Purpose |
|---|---|---|
HALO_API_URL |
http://localhost:8080 |
Address of the Go server. Server-rendered pages call it at runtime, and the forwarding rules for /api, /oauth2, /.well-known, /saml and /scim point at it. next build writes those rules into the build, so set the variable both when you build and when you run. |
HALO_WEB_DIST |
.next |
Directory for the Next.js build output. Lets you run two copies of the web interface from one checkout. |
PORT |
3200 in the Docker image |
Port of the production server in the Docker image. bun run dev and bun run start use port 3200. |
HOSTNAME |
0.0.0.0 in the Docker image |
Interface the production server binds to in the Docker image. |
Profile pictures and application logos
Without object storage, Halo keeps each profile picture and application logo in PostgreSQL. To keep them in an S3-compatible bucket instead, set all four of these. Halo still serves the images itself, at /api/v1/users/{id}/avatar and /api/v1/applications/{id}/logo, so the bucket can stay private. Applications that sign people in receive the picture URL.
| Variable | Purpose |
|---|---|
HALO_S3_ENDPOINT |
The S3 API address, without the bucket name. Cloudflare R2: https://<account>.r2.cloudflarestorage.com. Backblaze B2: https://s3.us-west-004.backblazeb2.com. iDrive e2: https://s3.us-east-1.idrivee2.com. MinIO: http://minio:9000. |
HALO_S3_BUCKET |
The bucket Halo writes avatars/<user id> and logos/<application id> into. |
HALO_S3_ACCESS_KEY_ID |
The access key. |
HALO_S3_SECRET_ACCESS_KEY |
The secret key. |
HALO_S3_REGION |
Optional. Defaults to auto, which Cloudflare R2 expects. Set the provider's region for Backblaze B2 and iDrive e2, such as us-west-004. |
Halo addresses the bucket by path, which these providers accept. Use the same keys you would give any other S3 client.
Docker Compose deployment
.env holds the values you choose. The install script writes it to the install directory, such as /opt/halo; in a checkout of the repository it is deploy/.env. compose.yml sets HALO_PUBLIC_URL, HALO_DATABASE_URL and HALO_TRUSTED_PROXIES from them, and the other server variables above keep their defaults unless you add them to .env. Two variables are used only by the Compose files:
| Variable | Purpose |
|---|---|
HALO_DOMAIN |
The domain Caddy obtains a certificate for and serves Halo on. HALO_PUBLIC_URL is built from it. |
POSTGRES_PASSWORD |
The password of the halo database user. HALO_DATABASE_URL is built from it. |
Development and tests
| Variable | Default | Purpose |
|---|---|---|
HALO_TEST_DATABASE_URL |
postgres://halo:halo@localhost:5436/halo |
The server where go test creates a throwaway database for each test. The user needs permission to create databases. |
HALO_URL |
http://localhost:3200 |
The Halo address the end-to-end test runs against. |
The example application in examples/go-web-client reads CLIENT_ID and CLIENT_SECRET from the environment. It also reads HALO_ISSUER (default http://localhost:3200), REDIRECT_URI (default http://localhost:9000/callback) and LISTEN (default localhost:9000).
Organization settings
Some settings live in the database rather than in environment variables, so you change them in the console without restarting Halo. Halo reads them again within 30 seconds of a change.
| Setting | Console page | Default | Range | Who can change it |
|---|---|---|---|---|
| Organization name | Organization | HALO_ORGANIZATION |
Up to 100 characters | Global administrator |
| Contact email | Organization | Empty | Global administrator | |
| Sign-in message | Branding | Empty | Up to 500 characters | Global administrator |
| Logo | Branding | None | PNG, JPEG or WebP, up to 256 KB | Global administrator |
| Colours | Branding | Halo's | Six hex colours | Global administrator |
| Custom CSS | Branding | Empty | Up to 32 KB | Global administrator |
| Branding in the console | Branding | Off | Global administrator | |
| Session lifetime | Security defaults | 12 hours | 1 to 72 hours | Security administrator |
| Lockout threshold | Security defaults | 5 failed passwords or codes | 3 to 20 | Security administrator |
| Lockout window | Security defaults | 15 minutes | 5 minutes to 24 hours | Security administrator |
| Setup link lifetime | Security defaults | 7 days | 1 to 30 days | Security administrator |
| Access token lifetime for new applications | Security defaults | 15 minutes | 5 minutes to 24 hours | Security administrator |
| ID token lifetime for new applications | Security defaults | 15 minutes | 5 minutes to 24 hours | Security administrator |
| Refresh token lifetime for new applications | Security defaults | 8 hours | 1 hour to 90 days | Security administrator |
| SSH certificate lifetime | Infrastructure access | 8 hours | 5 minutes to 24 hours | Security administrator |
| Who can use a password | Methods | Everyone | Everyone, or selected groups | Security administrator |
| Second factor for passwords | Methods | On | Security administrator | |
| Breached password check | Methods | On | Security administrator |
A new session lifetime applies to sessions that start afterwards. The token lifetimes are defaults for applications created afterwards; change an existing application's lifetimes on its own page.
The API exposes these settings at GET and PATCH /api/v1/settings. The password rules are passwordGroupIds, a list of group ids where an empty list allows everyone, passwordSecondFactor and passwordBreachCheck. They matter only while passwords are turned on under Methods; turn the breach check off when Halo has no internet access. Passwords describes them.
Colours and custom CSS
The sign-in, setup and account pages show your logo and sign-in message in Halo's own colours until you change them under Branding.
Colours. Six colours, each a six-digit hex value such as #2563eb: the accent for buttons and highlights, the background, the surface of cards and panels, the border, the text and the link colour. Halo derives the rest, such as hover and pressed states, tints and secondary text, from them. A colour you leave empty keeps Halo's. The page previews the sign-in card as you type, warns when text, secondary text or button labels fall under a 4.5:1 contrast ratio against their backgrounds, and Reset to Halo defaults clears every colour.
Custom CSS. A stylesheet added after Halo's on the same pages, for what the colours do not cover, such as fonts, corner radius, spacing or hiding an element. It may be up to 32 KB and must not contain </, which would end the style element; write \3c/ in a CSS string instead. Images, fonts and @import rules in it load only from Halo's own address, because every page carries a Content Security Policy that allows stylesheets, fonts and scripts from Halo's origin only and images from there or data: URLs. Turn on Use the colours and custom CSS in the admin console too to apply both to the console as well. Pages pick up a change within 30 seconds. If a stylesheet makes the sign-in page unusable, start Halo with HALO_DISABLE_CUSTOM_CSS=1, fix it, and remove the variable again.
Only a global administrator can change colours, custom CSS and the console switch, and each change writes a settings.update audit event naming what changed. Through the API, PATCH /api/v1/settings takes theme, an object with accent, background, surface, border, text and link, where an empty string keeps Halo's colour; customCss; and consoleBranding. GET /api/v1/organization returns the same three fields to every page without authentication. The organization JSON export includes the colours, custom CSS and console switch under settings.
Fixed values
These values cannot be changed in this version:
| What | Value |
|---|---|
| Magic sign-in links | Expire after 10 minutes; at most 5 per person in 15 minutes |
| Passkey and authenticator setup steps | Expire after 5 minutes |
| Sign-in requests from applications | Expire after 15 minutes |
| Federated sign-in attempts | Expire after 10 minutes |
Device codes for halo login |
Expire after 10 minutes |
| Client secrets | Valid for 365 days |
| Old secrets after rotation | Stop working after 24 hours |
| Previous OpenID Connect signing keys after rotation | Stay published in /oauth2/keys for 7 days |
| Email delivery | Up to 5 attempts within 1 day |
| Webhook delivery | Up to 8 attempts over about an hour |