Skip to content

General

Variable Default Description
HBOX_MODE development application mode used for runtime behavior can be one of: development, production
HBOX_WEB_PORT 7745 port to run the web server on, if you’re using docker do not change this
HBOX_WEB_HOST host to run the web server on, if you’re using docker do not change this. see below for examples
HBOX_WEB_MAX_UPLOAD_SIZE 10 maximum file upload size supported in MB
HBOX_WEB_READ_TIMEOUT 10s Read timeout of HTTP sever
HBOX_WEB_WRITE_TIMEOUT 10s Write timeout of HTTP server
HBOX_WEB_IDLE_TIMEOUT 30s Idle timeout of HTTP server
HBOX_STORAGE_CONN_STRING file:///./ path to the data directory, do not change this if you’re using docker
HBOX_STORAGE_PREFIX_PATH .data prefix path for the storage, if not set the storage will be used as is
HBOX_LOG_LEVEL info log level to use, can be one of trace, debug, info, warn, error, fatal, panic
HBOX_LOG_FORMAT text log format to use, can be one of: text, json
HBOX_MAILER_HOST email host to use, if not set no email provider will be used
HBOX_MAILER_PORT email port to use (no default — typically 587 for STARTTLS or 465 for implicit TLS)
HBOX_MAILER_USERNAME email user to use
HBOX_MAILER_PASSWORD email password to use
HBOX_MAILER_FROM email from address to use
HBOX_DATABASE_DRIVER sqlite3 sets the correct database type (sqlite3 or postgres)
HBOX_DATABASE_SQLITE_PATH ./.data/homebox.db?_pragma=busy_timeout=999&_pragma=journal_mode=WAL&_fk=1&_time_format=sqlite sets the directory path for Sqlite
HBOX_DATABASE_HOST sets the hostname for a postgres database
HBOX_DATABASE_PORT sets the port for a postgres database
HBOX_DATABASE_USERNAME sets the username for a postgres connection (optional if using cert auth)
HBOX_DATABASE_PASSWORD sets the password for a postgres connection (optional if using cert auth)
HBOX_DATABASE_DATABASE sets the database for a postgres connection
HBOX_DATABASE_SSL_MODE require sets the sslmode for a postgres connection
HBOX_DATABASE_SSL_CERT sets the sslcert for a postgres connection (should be a path)
HBOX_DATABASE_SSL_KEY sets the sslkey for a postgres connection (should be a path)
HBOX_DATABASE_SSL_ROOT_CERT sets the sslrootcert for a postgres connection (should be a path)
HBOX_DATABASE_PUB_SUB_CONN_STRING mem://{{ .Topic }} connection string for pub/sub messaging
HBOX_OPTIONS_ALLOW_REGISTRATION true allow users to register themselves
HBOX_OPTIONS_AUTO_INCREMENT_ASSET_ID true auto-increments the asset_id field for new items
HBOX_OPTIONS_CURRENCY_CONFIG json configuration file containing additional currencies
HBOX_OPTIONS_ALLOW_ANALYTICS false Allows the homebox team to view extremely basic information about the system that your running on. This helps make decisions regarding builds and other general decisions.
HBOX_OPTIONS_GITHUB_RELEASE_CHECK true check for new github releases
HBOX_OPTIONS_ALLOW_LOCAL_LOGIN true allow users to login with username/password when OIDC is enabled
HBOX_OPTIONS_TRUST_PROXY false trust proxy headers for determining request scheme (X-Forwarded-Proto)
HBOX_OPTIONS_HOSTNAME override hostname used for OIDC redirect URLs and other absolute URLs
HBOX_SEARCH_DRIVER database selects the free-text search engine: database (searches directly in SQLite/PostgreSQL, no extra services needed) or meilisearch. See the Search page.
HBOX_SEARCH_MEILISEARCH_HOST http://localhost:7700 URL of the Meilisearch instance (when HBOX_SEARCH_DRIVER=meilisearch)
HBOX_SEARCH_MEILISEARCH_API_KEY Meilisearch API key
HBOX_SEARCH_MEILISEARCH_INDEX homebox_entities Meilisearch index uid Homebox stores entity documents in
HBOX_SEARCH_MEILISEARCH_MAX_HITS 1000 maximum matches retrieved per search before database filters and pagination are applied
HBOX_AUTH_API_KEY_PEPPER Required. Server-side secret HMAC-keyed into stored API key hashes; the binary refuses to start if this is shorter than 32 bytes. Generate with openssl rand -base64 48. Must stay stable across restarts — rotating it invalidates every issued API key.
HBOX_AUTH_RATE_LIMIT_ENABLED true enable rate limiting for authentication attempts
HBOX_AUTH_RATE_LIMIT_MAX_ATTEMPTS 5 maximum number of failed authentication attempts before rate limiting
HBOX_AUTH_RATE_LIMIT_WINDOW 1m time window for rate limiting
HBOX_AUTH_RATE_LIMIT_BASE_BACKOFF 10s base backoff duration for rate limiting
HBOX_AUTH_RATE_LIMIT_MAX_BACKOFF 5m maximum backoff duration for rate limiting
HBOX_DEBUG_ENABLED false enable debug mode (exposes pprof + expvar handlers and prints the loaded configuration to stdout with secrets redacted). The debug listener binds to loopback only (127.0.0.1); tunnel via SSH if remote access is needed.
HBOX_DEBUG_PORT 4000 port to run debug server on (always bound to 127.0.0.1)
HBOX_DEMO false enable demo mode, which seeds a demo@example.com user and sample inventory on first boot. When HBOX_MODE=production the app refuses to start with demo enabled unless HBOX_DEMO_PASSWORD is also set (the public demo/demodemo default would otherwise be guessable on a reachable host).
HBOX_DEMO_PASSWORD password for the seeded demo user. Required (minimum 12 characters) when HBOX_DEMO=true and HBOX_MODE=production. In development mode an unset value falls back to the public default demodemo.
HBOX_OIDC_ENABLED false enable OpenID Connect (OIDC) authentication
HBOX_OIDC_ISSUER_URL OIDC provider issuer URL (required when OIDC is enabled)
HBOX_OIDC_DISCOVERY_URL URL to fetch the provider’s /.well-known/openid-configuration from, when it isn’t the issuer URL. ID tokens must still come from HBOX_OIDC_ISSUER_URL
HBOX_OIDC_CLIENT_ID OIDC client ID (required when OIDC is enabled)
HBOX_OIDC_CLIENT_SECRET OIDC client secret (required when OIDC is enabled)
HBOX_OIDC_SCOPE openid profile email OIDC scopes to request from the provider
HBOX_OIDC_ALLOWED_GROUPS comma-separated list of groups that are allowed to login (empty means all groups allowed)
HBOX_OIDC_AUTO_REDIRECT false auto redirect to OIDC authentication (automatically redirects to OIDC provider, but does not disable local login. See HBOX_OPTIONS_ALLOW_LOCAL_LOGIN)
HBOX_OIDC_VERIFY_EMAIL false require email verification from OIDC provider
HBOX_OIDC_GROUP_CLAIM groups name of the claim in the ID token that contains user groups
HBOX_OIDC_EMAIL_CLAIM email name of the claim in the ID token that contains user email
HBOX_OIDC_NAME_CLAIM name name of the claim in the ID token that contains user display name
HBOX_OIDC_EMAIL_VERIFIED_CLAIM email_verified name of the claim in the ID token that contains user email verification status
HBOX_OIDC_BUTTON_TEXT Sign in with OIDC text displayed on the OIDC login button
HBOX_OIDC_STATE_EXPIRY 10m how long OIDC state parameters are valid (for CSRF protection)
HBOX_OIDC_REQUEST_TIMEOUT 30s timeout for OIDC provider requests (token exchange, userinfo, etc.)
HBOX_LABEL_MAKER_WIDTH 526 width for generated labels in pixels
HBOX_LABEL_MAKER_HEIGHT 200 height for generated labels in pixels
HBOX_LABEL_MAKER_MARGIN 32 margin around label
HBOX_LABEL_MAKER_PADDING 32 space between elements on label
HBOX_LABEL_MAKER_FONT_SIZE 32.0 font size for label text
HBOX_LABEL_MAKER_PRINT_COMMAND the command used to print labels, for both the basic label and label templates. if empty, server-side printing is disabled. The command is split into arguments before substitution. Placeholders: {{.FileName}} (png path), {{.Width}}/{{.Height}} (pixels), {{.WidthMm}}/{{.HeightMm}}, {{.Dpi}}, {{.TitleText}}, {{.URL}} and {{.Copies}} (if present the command runs once with the count, otherwise once per copy). Example: lp -d labelprinter {{.FileName}}
HBOX_LABEL_MAKER_DYNAMIC_LENGTH true allow label generation with open length. HBOX_LABEL_MAKER_HEIGHT is still used for layout and minimal height. If not used, long text may be cut off, but all labels have the same size.
HBOX_LABEL_MAKER_ADDITIONAL_INFORMATION Additional information added to the label like name or phone number
HBOX_LABEL_MAKER_REGULAR_FONT_PATH path to regular font file for label generation (e.g., /fonts/NotoSansKR-Regular.ttf). If not set, uses embedded font. Supports TTF format.
HBOX_LABEL_MAKER_BOLD_FONT_PATH path to bold font file for label generation (e.g., /fonts/NotoSansKR-Bold.ttf). If not set, uses embedded font. Supports TTF format.
HBOX_LABEL_MAKER_LABEL_SERVICE_URL URL for label service
HBOX_LABEL_MAKER_LABEL_SERVICE_TIMEOUT timeout for label service requests
HBOX_THUMBNAIL_ENABLED true enable thumbnail generation for images, supports PNG, JPEG, AVIF, WEBP, GIF file types
HBOX_THUMBNAIL_WIDTH 500 width for generated thumbnails in pixels
HBOX_THUMBNAIL_HEIGHT 500 height for generated thumbnails in pixels
HBOX_BARCODE_TOKEN_BARCODESPIDER API token for BarcodeSpider.com service used for barcode product lookups. If not set, BarcodeSpider lookups will not be performed.
HBOX_BARCODE_OPEN_FOOD_FACTS_CONTACT Optional contact value included in the User-Agent for Open Food Facts, Open Beauty Facts, and Open Products Facts barcode lookups. This is sent to third-party APIs, so avoid secrets or personal PII and prefer a role/contact alias.
HBOX_NOTIFIER_ALLOW_NETS semicolon-separated list of CIDR networks to allow for notifiers (e.g., 192.168.1.0/24;10.0.0.0/8). If set, only these networks will be allowed and all block rules are bypassed.
HBOX_NOTIFIER_BLOCK_NETS semicolon-separated list of CIDR networks to block for notifiers (e.g., 192.168.1.0/24;10.0.0.0/8). Provides fine-grained blocking without enabling blanket rules.
HBOX_NOTIFIER_BLOCK_LOCALHOST true block notifiers from sending to localhost/loopback addresses (127.0.0.1, ::1)
HBOX_NOTIFIER_BLOCK_LOCAL_NETS false block notifiers from sending to RFC1918 private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
HBOX_NOTIFIER_BLOCK_BOGON_NETS true block notifiers from sending to bogon/reserved networks (link-local, multicast, broadcast, etc.)
HBOX_NOTIFIER_BLOCK_CLOUD_METADATA true block notifiers from sending to cloud metadata endpoints (169.254.169.254, fd00:ec2::254)
HBOX_NOTIFIER_DNS64_NETS 64:ff9b::/96;64:ff9b:1::/48 semicolon-separated list of DNS64/NAT64 translation prefixes (RFC 6052). IPv6 addresses in these prefixes have their embedded IPv4 address extracted and checked against the allow/block rules, preventing DNS64-based SSRF bypasses. Override if your NAT64 deployment uses a custom prefix.
HBOX_OTEL_ENABLED false enable OpenTelemetry tracing. Standard OTEL_* env vars are also honored by the SDK in addition to these HBOX_OTEL_* options.
HBOX_OTEL_SERVICE_NAME homebox service name reported to the telemetry backend
HBOX_OTEL_SERVICE_VERSION service version reported to the telemetry backend (defaults to the build version when unset)
HBOX_OTEL_EXPORTER otlp exporter type: otlp, stdout, or none
HBOX_OTEL_ENDPOINT OTLP exporter endpoint including host and port, e.g. localhost:4317 for gRPC or http://localhost:4318 for HTTP
HBOX_OTEL_PATH_PREFIX optional URL path prefix appended to the OTLP HTTP exporter endpoint
HBOX_OTEL_PROTOCOL grpc OTLP protocol: grpc or http
HBOX_OTEL_INSECURE false disable TLS for the OTLP exporter connection
HBOX_OTEL_HEADERS additional headers to send with OTLP requests as comma-separated key=value pairs (e.g. an auth header for a managed backend; treated as a secret and redacted from debug output)
HBOX_OTEL_SAMPLE_RATE 1.0 trace sampling rate from 0.0 (no traces) to 1.0 (all traces)
HBOX_OTEL_ENABLE_METRICS true enable OpenTelemetry metrics collection
HBOX_OTEL_METRICS_INTERVAL 15s interval at which metrics are exported (e.g. 15s, 1m)
HBOX_OTEL_ENABLE_LOGGING true bridge zerolog into the OpenTelemetry logs pipeline
HBOX_OTEL_ENABLE_DATABASE_TRACING true emit spans for database operations
HBOX_OTEL_ENABLE_HTTP_TRACING true emit spans for HTTP requests
HBOX_OTEL_PROXY_ENABLED true enable the in-process telemetry proxy endpoint that forwards frontend trace data to the configured exporter

Any HBOX_* environment variable can also be set from a file by appending _FILE to its name and pointing it at the file, e.g. HBOX_AUTH_API_KEY_PEPPER_FILE=/run/secrets/homebox_pepper. This works with Docker and Kubernetes secrets or systemd credentials, so secrets don’t need to be stored in plain environment variables. Trailing newlines are trimmed, and the _FILE variant takes precedence when both are set.

services:
homebox:
image: ghcr.io/sysadminsmedia/homebox:latest
environment:
HBOX_AUTH_API_KEY_PEPPER_FILE: /run/secrets/homebox_pepper
secrets:
- homebox_pepper
secrets:
homebox_pepper:
file: ./homebox_pepper.txt
Value Notes
0.0.0.0 Visible all interfaces (default behaviour)
127.0.0.1 Only visible on same host
100.64.0.1 Only visible on a specific interface (e.g., VPN in a VPS).
unix?path=/run/homebox.sock Listen on unix socket at specified path
sysd?name=homebox.socket Listen on systemd socket

For unix and systemd socket address syntax and available options, see the anyhttp address-syntax documentation.

Below example starts homebox in an isolated network. The process cannot make any external requests (including check for newer release) and thus more secure.

Terminal window
❯ sudo systemd-run --property=PrivateNetwork=yes --uid $UID --pty --same-dir --wait --collect homebox --web-host "unix?path=/run/user/$UID/homebox.sock"
Running as unit: run-p74482-i74483.service
Press ^] three times within 1s to disconnect TTY.
2025/07/11 22:33:29 goose: no migrations to run. current version: 20250706190000
10:33PM INF ../../../go/src/app/app/api/handlers/v1/v1_ctrl_auth.go:98 > registering auth provider name=local
10:33PM INF ../../../go/src/app/app/api/main.go:275 > Server is running on unix?path=/run/user/1000/homebox.sock
10:33PM ERR ../../../go/src/app/app/api/main.go:403 > failed to get latest github release error="failed to make latest version request: Get \"https://api.github.com/repos/sysadminsmedia/homebox/releases/l
atest\": dial tcp: lookup api.github.com on [::1]:53: read udp [::1]:50951->[::1]:53: read: connection refused"
10:33PM INF ../../../go/src/app/internal/web/mid/logger.go:36 > request received method=GET path=/ rid=hname/PoXyRgt6ol-000001
10:33PM INF ../../../go/src/app/internal/web/mid/logger.go:41 > request finished method=GET path=/ rid=hname/PoXyRgt6ol-000001 status=0

In the example below, Homebox listens on a systemd socket securely so that only the webserver (Caddy) can access it. Other processes/containers on the host cannot connect to Homebox directly, bypassing the webserver.

File: homebox.socket

/usr/local/lib/systemd/system/homebox.socket
[Unit]
Description=Homebox socket
[Socket]
ListenStream=/run/homebox.sock
SocketGroup=caddy
SocketMode=0660
[Install]
WantedBy=sockets.target

File: homebox.service

/usr/local/lib/systemd/system/homebox.service
[Unit]
Description=Homebox
After=network.target
Documentation=https://homebox.software
[Service]
DynamicUser=yes
StateDirectory=homebox
Environment=HBOX_WEB_HOST=sysd?name=homebox.socket
WorkingDirectory=/var/lib/homebox
ExecStart=/usr/local/bin/homebox
NoNewPrivileges=yes
CapabilityBoundingSet=
RestrictNamespaces=true
SystemCallFilter=@system-service

Usage:

Terminal window
systemctl start homebox.socket