Skip to content
Homebox

General

Env Variables & Configuration

Section titled “Env Variables & Configuration”
VariableDefaultDescription
HBOX_MODEdevelopmentapplication mode used for runtime behavior can be one of: development, production
HBOX_WEB_PORT7745port to run the web server on, if you’re using docker do not change this
HBOX_WEB_HOSThost to run the web server on, if you’re using docker do not change this. see below for examples
HBOX_WEB_MAX_UPLOAD_SIZE10maximum file upload size supported in MB
HBOX_WEB_READ_TIMEOUT10sRead timeout of HTTP sever
HBOX_WEB_WRITE_TIMEOUT10sWrite timeout of HTTP server
HBOX_WEB_IDLE_TIMEOUT30sIdle timeout of HTTP server
HBOX_STORAGE_CONN_STRINGfile:///./path to the data directory, do not change this if you’re using docker
HBOX_STORAGE_PREFIX_PATH.dataprefix path for the storage, if not set the storage will be used as is
HBOX_LOG_LEVELinfolog level to use, can be one of trace, debug, info, warn, error, fatal, panic
HBOX_LOG_FORMATtextlog format to use, can be one of: text, json
HBOX_MAILER_HOSTemail host to use, if not set no email provider will be used
HBOX_MAILER_PORTemail port to use (no default — typically 587 for STARTTLS or 465 for implicit TLS)
HBOX_MAILER_USERNAMEemail user to use
HBOX_MAILER_PASSWORDemail password to use
HBOX_MAILER_FROMemail from address to use
HBOX_DATABASE_DRIVERsqlite3sets 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=sqlitesets the directory path for Sqlite
HBOX_DATABASE_HOSTsets the hostname for a postgres database
HBOX_DATABASE_PORTsets the port for a postgres database
HBOX_DATABASE_USERNAMEsets the username for a postgres connection (optional if using cert auth)
HBOX_DATABASE_PASSWORDsets the password for a postgres connection (optional if using cert auth)
HBOX_DATABASE_DATABASEsets the database for a postgres connection
HBOX_DATABASE_SSL_MODErequiresets the sslmode for a postgres connection
HBOX_DATABASE_SSL_CERTsets the sslcert for a postgres connection (should be a path)
HBOX_DATABASE_SSL_KEYsets the sslkey for a postgres connection (should be a path)
HBOX_DATABASE_SSL_ROOT_CERTsets the sslrootcert for a postgres connection (should be a path)
HBOX_DATABASE_PUB_SUB_CONN_STRINGmem://{{ .Topic }}connection string for pub/sub messaging
HBOX_OPTIONS_ALLOW_REGISTRATIONtrueallow users to register themselves
HBOX_OPTIONS_AUTO_INCREMENT_ASSET_IDtrueauto-increments the asset_id field for new items
HBOX_OPTIONS_CURRENCY_CONFIGjson configuration file containing additional currencies
HBOX_OPTIONS_ALLOW_ANALYTICSfalseAllows 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_CHECKtruecheck for new github releases
HBOX_OPTIONS_ALLOW_LOCAL_LOGINtrueallow users to login with username/password when OIDC is enabled
HBOX_OPTIONS_TRUST_PROXYfalsetrust proxy headers for determining request scheme (X-Forwarded-Proto)
HBOX_OPTIONS_HOSTNAMEoverride hostname used for OIDC redirect URLs and other absolute URLs
HBOX_AUTH_API_KEY_PEPPERRequired. 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_ENABLEDtrueenable rate limiting for authentication attempts
HBOX_AUTH_RATE_LIMIT_MAX_ATTEMPTS5maximum number of failed authentication attempts before rate limiting
HBOX_AUTH_RATE_LIMIT_WINDOW1mtime window for rate limiting
HBOX_AUTH_RATE_LIMIT_BASE_BACKOFF10sbase backoff duration for rate limiting
HBOX_AUTH_RATE_LIMIT_MAX_BACKOFF5mmaximum backoff duration for rate limiting
HBOX_DEBUG_ENABLEDfalseenable 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_PORT4000port to run debug server on (always bound to 127.0.0.1)
HBOX_DEMOfalseenable 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_PASSWORDpassword 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_ENABLEDfalseenable OpenID Connect (OIDC) authentication
HBOX_OIDC_ISSUER_URLOIDC provider issuer URL (required when OIDC is enabled)
HBOX_OIDC_CLIENT_IDOIDC client ID (required when OIDC is enabled)
HBOX_OIDC_CLIENT_SECRETOIDC client secret (required when OIDC is enabled)
HBOX_OIDC_SCOPEopenid profile emailOIDC scopes to request from the provider
HBOX_OIDC_ALLOWED_GROUPScomma-separated list of groups that are allowed to login (empty means all groups allowed)
HBOX_OIDC_AUTO_REDIRECTfalseauto redirect to OIDC authentication (automatically redirects to OIDC provider, but does not disable local login. See HBOX_OPTIONS_ALLOW_LOCAL_LOGIN)
HBOX_OIDC_VERIFY_EMAILfalserequire email verification from OIDC provider
HBOX_OIDC_GROUP_CLAIMgroupsname of the claim in the ID token that contains user groups
HBOX_OIDC_EMAIL_CLAIMemailname of the claim in the ID token that contains user email
HBOX_OIDC_NAME_CLAIMnamename of the claim in the ID token that contains user display name
HBOX_OIDC_EMAIL_VERIFIED_CLAIMemail_verifiedname of the claim in the ID token that contains user email verification status
HBOX_OIDC_BUTTON_TEXTSign in with OIDCtext displayed on the OIDC login button
HBOX_OIDC_STATE_EXPIRY10mhow long OIDC state parameters are valid (for CSRF protection)
HBOX_OIDC_REQUEST_TIMEOUT30stimeout for OIDC provider requests (token exchange, userinfo, etc.)
HBOX_LABEL_MAKER_WIDTH526width for generated labels in pixels
HBOX_LABEL_MAKER_HEIGHT200height for generated labels in pixels
HBOX_LABEL_MAKER_MARGIN32margin around label
HBOX_LABEL_MAKER_PADDING32space between elements on label
HBOX_LABEL_MAKER_FONT_SIZE32.0font size for label text
HBOX_LABEL_MAKER_PRINT_COMMANDthe command to use for printing labels. if empty, label printing is disabled. {{.FileName}} in the command will be replaced with the png filename of the label
HBOX_LABEL_MAKER_DYNAMIC_LENGTHtrueallow 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_INFORMATIONAdditional information added to the label like name or phone number
HBOX_LABEL_MAKER_REGULAR_FONT_PATHpath 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_PATHpath 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_URLURL for label service
HBOX_LABEL_MAKER_LABEL_SERVICE_TIMEOUTtimeout for label service requests
HBOX_THUMBNAIL_ENABLEDtrueenable thumbnail generation for images, supports PNG, JPEG, AVIF, WEBP, GIF file types
HBOX_THUMBNAIL_WIDTH500width for generated thumbnails in pixels
HBOX_THUMBNAIL_HEIGHT500height for generated thumbnails in pixels
HBOX_BARCODE_TOKEN_BARCODESPIDERAPI token for BarcodeSpider.com service used for barcode product lookups. If not set, BarcodeSpider lookups will not be performed.
HBOX_BARCODE_OPEN_FOOD_FACTS_CONTACTOptional 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_NETScomma-separated list of CIDR networks to allow for generic 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_NETScomma-separated list of CIDR networks to block for generic notifiers (e.g., 192.168.1.0/24,10.0.0.0/8). Provides fine-grained blocking without enabling blanket rules.
HBOX_NOTIFIER_BLOCK_LOCALHOSTfalseblock generic notifiers from sending to localhost/loopback addresses (127.0.0.1, ::1)
HBOX_NOTIFIER_BLOCK_LOCAL_NETSfalseblock generic 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_NETStrueblock generic notifiers from sending to bogon/reserved networks (link-local, multicast, broadcast, etc.)
HBOX_NOTIFIER_BLOCK_CLOUD_METADATAtrueblock generic notifiers from sending to cloud metadata endpoints (169.254.169.254, fd00:ec2::254)
HBOX_OTEL_ENABLEDfalseenable OpenTelemetry tracing. Standard OTEL_* env vars are also honored by the SDK in addition to these HBOX_OTEL_* options.
HBOX_OTEL_SERVICE_NAMEhomeboxservice name reported to the telemetry backend
HBOX_OTEL_SERVICE_VERSIONservice version reported to the telemetry backend (defaults to the build version when unset)
HBOX_OTEL_EXPORTERotlpexporter type: otlp, stdout, or none
HBOX_OTEL_ENDPOINTOTLP exporter endpoint including host and port, e.g. localhost:4317 for gRPC or http://localhost:4318 for HTTP
HBOX_OTEL_PATH_PREFIXoptional URL path prefix appended to the OTLP HTTP exporter endpoint
HBOX_OTEL_PROTOCOLgrpcOTLP protocol: grpc or http
HBOX_OTEL_INSECUREfalsedisable TLS for the OTLP exporter connection
HBOX_OTEL_HEADERSadditional 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_RATE1.0trace sampling rate from 0.0 (no traces) to 1.0 (all traces)
HBOX_OTEL_ENABLE_METRICStrueenable OpenTelemetry metrics collection
HBOX_OTEL_METRICS_INTERVAL15sinterval at which metrics are exported (e.g. 15s, 1m)
HBOX_OTEL_ENABLE_LOGGINGtruebridge zerolog into the OpenTelemetry logs pipeline
HBOX_OTEL_ENABLE_DATABASE_TRACINGtrueemit spans for database operations
HBOX_OTEL_ENABLE_HTTP_TRACINGtrueemit spans for HTTP requests
HBOX_OTEL_PROXY_ENABLEDtrueenable the in-process telemetry proxy endpoint that forwards frontend trace data to the configured exporter

HBOX_WEB_HOST examples

Section titled “HBOX_WEB_HOST examples”
ValueNotes
0.0.0.0Visible all interfaces (default behaviour)
127.0.0.1Only visible on same host
100.64.0.1Only visible on a specific interface (e.g., VPN in a VPS).
unix?path=/run/homebox.sockListen on unix socket at specified path
sysd?name=homebox.socketListen on systemd socket

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

Private network example

Section titled “Private network example”

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

Systemd socket example

Section titled “Systemd socket example”

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