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.

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 iss in 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_URL to use plain http,
• removes the Secure flag from Halo's cookies,
• lets the OpenID Connect provider run on plain http,
• enables halo seed-demo and halo dev-session,
• adds GET /api/v1/dev/outbox, which shows global administrators the 50 most recent emails,
• accepts http://localhost and http://127.0.0.1 as 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.

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 465 uses TLS from the start of the connection. On any other port, Halo requires STARTTLS, except when the host is localhost or a loopback address.
• With HALO_SMTP_USERNAME set, Halo authenticates with PLAIN using HALO_SMTP_USERNAME and HALO_SMTP_PASSWORD.

Web interface

The Next.js web interface reads these variables.

Docker Compose deployment

deploy/.env holds the server variables above plus two that only the Compose files use:

Development and tests

The example application in examples/go-web-client reads CLIENT_ID, CLIENT_SECRET, HALO_ISSUER, REDIRECT_URI and LISTEN; its README describes them.

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.

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.

Fixed values

These values cannot be changed in this version: