Configuration
Homestead needs no config file. The server reads these environment variables at start
(server/internal/config/config.go). Generated from the app repository at commit 5256875 (2026-10-24).
| Variable | Default | Meaning |
|---|---|---|
HOMESTEAD_LISTEN | :8080 | Listen address |
HOMESTEAD_DATA_DIR | /data | SQLite DB, media, secret key |
HOMESTEAD_BASE_URL | derived from request | Public URL used in share links, QR codes and MCP snippets |
HOMESTEAD_SECRET_KEY | generated into /data/secret.key on first run | Key for HMAC (media URLs) and AES-GCM (stored API keys). Not read on main yet: the server always uses the file secret.key in the data directory. |
HOMESTEAD_MDNS | true | Advertise _homestead._tcp on the LAN |
HOMESTEAD_TRUSTED_PROXIES | empty | CIDRs allowed to set X-Forwarded-*. Checked at start (a bad CIDR stops the server), but not yet used when reading client addresses. |
HOMESTEAD_LOG_LEVEL | info | debug, info, warn, error |
Where data lives
Section titled “Where data lives”Everything a household owns sits in HOMESTEAD_DATA_DIR (/data in the container): the
SQLite database, the media folder and secret.key. In Docker that’s one volume
(homestead-data in deploy/compose.yaml). Back it up with
homestead backup (see the CLI reference).
Behind a proxy or tunnel
Section titled “Behind a proxy or tunnel”Set HOMESTEAD_BASE_URL to the public address so share links, QR codes and MCP snippets
carry the right URL. HOMESTEAD_TRUSTED_PROXIES accepts your proxy’s address range, but on
main the server doesn’t read forwarded addresses yet.
The remote access guide walks through Tailscale, Cloudflare
Tunnel and Caddy.
In-app settings
Section titled “In-app settings”Fetch intervals, media retention, the X API key and budget, AI settings and household
details are set in the app (Settings), not in the environment. See
docs/09-screens.md § Settings.