Configure Breadbox with environment variables

Breadbox reads its configuration from environment variables at startup. Most settings can also be managed through the setup wizard or admin dashboard without restarting, but environment variables always take precedence.

Config precedence

When a setting exists in more than one place, Breadbox resolves it in this order:

Environment variable → dashboard settings → default

If you set PLAID_CLIENT_ID as an environment variable, the dashboard’s Plaid credentials field becomes read-only and displays a notice that the value is environment-controlled.

Provider credentials can also be configured through the setup wizard or admin dashboard — environment variables are optional but take precedence.

Required variables

You must set these before starting Breadbox. The process exits with a descriptive error if they are missing.

After setting env vars, run breadbox doctor to verify everything resolves cleanly — it checks DATABASE_URL, the encryption key, provider credentials, and more without booting the server. See Verify the install.

Variable	Description	Required
`DATABASE_URL`	PostgreSQL connection string, e.g. `postgres://user:pass@localhost:5432/breadbox?sslmode=disable`	Yes
`ENCRYPTION_KEY`	32-byte key as a 64-character hex string, used for AES-256-GCM encryption of bank credentials	Yes (with Plaid or Teller)

Generate your encryption key

Run the following command once and save the output as the value of ENCRYPTION_KEY:

openssl rand -hex 32

Never change ENCRYPTION_KEY after bank connections have been created. All stored provider credentials (Plaid and Teller access tokens) are encrypted with this key. Changing it makes every existing credential permanently unreadable and forces all household members to re-link their bank accounts. Back up this value separately from your database — see the backup guide.

Optional variables

These variables are not required. If omitted, Breadbox uses the value stored in the database or the built-in default.

Variable	Default	Description
`SERVER_PORT`	`8080`	HTTP listen port
`ENVIRONMENT`	`local`	Set to `local` for local development (text logs, debug level) or `docker` for production (JSON logs, info level)
`DOMAIN`	(unset)	Public hostname for HTTPS (e.g. `breadbox.example.com`). Enables the `caddy` Docker Compose profile that requests Let’s Encrypt certificates automatically. Leave unset for localhost-only installs.
`PLAID_CLIENT_ID`	(from dashboard)	Plaid API client ID
`PLAID_SECRET`	(from dashboard)	Plaid API secret
`PLAID_ENV`	(from dashboard)	Plaid environment: `sandbox`, `development`, or `production`
`TELLER_APP_ID`	(from dashboard)	Teller application ID
`TELLER_CERT_PATH`	(env-only)	Absolute path to your Teller `cert.pem` file on the server filesystem. Cannot be set via dashboard.
`TELLER_KEY_PATH`	(env-only)	Absolute path to your Teller `private-key.pem` file on the server filesystem. Cannot be set via dashboard.
`TELLER_ENV`	(from dashboard)	Teller environment: `sandbox`, `development`, or `production`
`TELLER_WEBHOOK_SECRET`	(from dashboard)	HMAC signing secret from the Teller Dashboard. Required when you configure a webhook URL.

Dashboard-managed settings

The following settings are configured through the setup wizard or the Settings page in the admin dashboard. They are stored in the database and take effect immediately — no restart required.

Plaid credentials — client ID, secret, and environment
Sync interval — how often Breadbox polls for new transactions: every 4, 8, 12, or 24 hours (default: 12)
Webhook URL — the public base URL where Plaid sends transaction webhook events

If you set PLAID_CLIENT_ID, PLAID_SECRET, or PLAID_ENV as environment variables, the corresponding dashboard fields become read-only.

Example .env file

Copy .env.example from the repository and fill in your values:

# Required
DATABASE_URL=postgres://breadbox:breadbox@localhost:5432/breadbox?sslmode=disable
ENCRYPTION_KEY=<output of openssl rand -hex 32>

# Optional
SERVER_PORT=8080
ENVIRONMENT=local

# Plaid (can be set here or in the admin dashboard)
PLAID_CLIENT_ID=
PLAID_SECRET=
PLAID_ENV=sandbox

For Docker deployments, save this as .docker.env and set ENVIRONMENT=docker.

Overview

Bank Connections

Transactions

AI Integration

Configuration

Configure Breadbox with environment variables

Config precedence

Required variables

Generate your encryption key

Optional variables

Dashboard-managed settings

Example .env file

​Config precedence

​Required variables

​Generate your encryption key

​Optional variables

​Dashboard-managed settings

​Example .env file

Config precedence

Required variables

Generate your encryption key

Optional variables

Dashboard-managed settings

Example .env file