Skip to main content
Breadbox runs in minutes — after that, any MCP-compatible AI agent can query your bank data. The one-liner below handles Docker, generates your secrets, optionally wires up HTTPS, and starts the stack on your machine. The one-liner itself finishes in about 2 minutes; first-run setup (admin account + bank provider + first sync) takes another 5–10 minutes.

​
Quick install

Run this on the machine where you want Breadbox to live — a VPS, a spare laptop, a NAS with Docker, anywhere docker can run. breadbox.sh/install.sh is a thin bootstrap shim that downloads the real installer from the canalesb93/breadbox GitHub repo; you can read the script before piping it to bash. 
curl -fsSL https://breadbox.sh/install.sh | bash
What the installer does, in order:
1

Detects your platform

Reads your OS (macOS / Linux) and architecture (amd64 / arm64) so it can pick the right binary.
2

Checks Docker

If Docker is missing on Linux, the installer offers to install it for you via the official get.docker.com script. On macOS you’ll need Docker Desktop installed already.
3

Prompts for a public domain (optional)

Enter a hostname if you have one ready (e.g. breadbox.example.com) to enable HTTPS via . Leave blank for a localhost-only install — you can add a domain later.
4

Generates secrets and Compose config

Creates your ENCRYPTION_KEY and Postgres password, then writes a version-pinned docker-compose.prod.yml to the install directory. Both secrets land in .env — back up this file; see the ENCRYPTION_KEY notes below.
5

Starts the stack

Runs docker compose up -d and waits for the containers to become healthy.
6

Offers to run on boot

On Linux, registers a systemd unit; on macOS, a launchd agent. Either way, Breadbox starts automatically when your machine reboots.
7

Runs `breadbox doctor`

A pre-flight health check confirms your config, database, and encryption key are all consistent. You should see all green checks.
If breadbox.sh is unreachable, the direct URL works the same way: 
curl -fsSL https://raw.githubusercontent.com/canalesb93/breadbox/main/deploy/install.sh | bash

​
Non-interactive install

Skip the prompts and configure a public domain in one shot: 
curl -fsSL https://breadbox.sh/install.sh | bash -s -- --yes --domain=breadbox.example.com
  • --yes accepts all defaults — random generated credentials, auto-detected architecture, daemon registration — and skips interactive prompts. Use this in CI or when you want a hands-off install.
  • --domain=<host> enables the — a reverse proxy on :80/:443 that requests HTTPS certificates automatically. Without --domain, Caddy is left off and ports 80/443 stay free on your host.

​
Install directory

InvocationInstall location
sudo bash ... (root)/opt/breadbox
regular user$HOME/.breadbox
overrideINSTALL_DIR=/custom/path bash install.sh

​
Updates

When a newer release ships, the dashboard surfaces a notice and you update with two commands from the install directory: 
cd ~/.breadbox        # or /opt/breadbox for a root install
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
Your data and .env are preserved and database migrations run on the next start. See Updating Breadbox for every install method, version pinning, verification, and rollback.

​
Back up your .env file

The installer writes your ENCRYPTION_KEY to .env and you don’t need to do anything with it day to day — Breadbox decrypts your bank credentials automatically on every run. But if you ever lose .env (host migration, accidental rm, container volume wipe), the encrypted bank credentials in your database become unrecoverable.
Copy .env somewhere safe outside the install directory — a password manager vault, a secure notes app, or an encrypted backup. You can always re-generate the other vars, but ENCRYPTION_KEY is the one that matters.

​
Are you planning to use cloud AI clients?

Need Claude, ChatGPT, or other cloud AI to reach Breadbox?

Cloud AI clients and real-time webhooks from Plaid/Teller need a public HTTPS URL, not localhost. If you want any of that, follow the Remote Hosting guide — exe.dev, Cloudflare Tunnel, Caddy on a VPS, and Tailscale Funnel walkthroughs. Localhost-only is fine if you’re just evaluating, or if the only agent touching Breadbox is a local autonomous runner (e.g., Openclaw on the same machine).

​
Alternative install methods

The one-liner above is the supported default. The methods below are for specific cases: integrating Breadbox into an existing Compose stack, running without Docker, or hacking on the source.
Use this if you already manage a Compose stack and want to drop Breadbox into it yourself.
1

Download the Compose file

mkdir breadbox && cd breadbox
curl -O https://raw.githubusercontent.com/canalesb93/breadbox/main/deploy/docker-compose.prod.yml
mv docker-compose.prod.yml docker-compose.yml
2

Create your .env file

cat > .env <<EOF
DATABASE_URL=postgres://breadbox:breadbox@db:5432/breadbox?sslmode=disable
ENCRYPTION_KEY=$(openssl rand -hex 32)
SERVER_PORT=8080
ENVIRONMENT=docker
POSTGRES_USER=breadbox
POSTGRES_PASSWORD=$(openssl rand -base64 32 | tr -d '=/+')
POSTGRES_DB=breadbox
EOF
Save .env somewhere safe (password manager, secure notes, encrypted backup). ENCRYPTION_KEY encrypts your stored bank credentials — if it’s lost, those credentials can’t be recovered and every bank has to be re-linked.
3

Start Breadbox

Localhost-only (Caddy stays off):
docker compose up -d breadbox db
Or with the Caddy HTTPS reverse proxy (set DOMAIN= in .env first):
docker compose --profile caddy up -d
Caddy only binds ports 80/443 when you pass --profile caddy. Open http://your-host:8080 (or your HTTPS domain) to hit the setup wizard.
Pin a specific version in docker-compose.yml:
image: ghcr.io/canalesb93/breadbox:v0.1.0

​
Environment variables

Most Breadbox configuration is done through environment variables. The one-liner and Docker Compose methods generate these for you automatically — you only need this table if you’re doing a manual or binary install. The table below covers the essentials; the environment variables reference documents every variable, precedence rules, and how env vars interact with dashboard settings.
VariableRequiredDescription
DATABASE_URLYesPostgreSQL connection string, e.g. postgres://user:pass@host:5432/breadbox?sslmode=disable
ENCRYPTION_KEYYes32-byte key as a 64-character hex string. Generate with openssl rand -hex 32. Required when any bank provider is configured.
SERVER_PORTNoHTTP listen port. Defaults to 8080.
DOMAINNoPublic hostname (e.g. breadbox.example.com). Enables the caddy compose profile for automatic HTTPS; leave unset for localhost-only installs.
PLAID_CLIENT_IDNoPlaid API client ID. Can also be set through the setup wizard.
PLAID_SECRETNoPlaid API secret. Can also be set through the setup wizard.
TELLER_APP_IDNoTeller application ID. Can also be set through the setup wizard.
Not sure whether to use Plaid or Teller? Start with Teller — its free Development tier connects to real bank accounts with no production approval required; Plaid has broader US coverage but takes more setup. Either way, you can skip the credentials in .env and configure them from the setup wizard later. See Bank Connections for the full comparison.

​
Verify the install

After the installer finishes, run breadbox doctor to confirm everything is healthy — you should see all checks pass in green: 
# Docker install: exec into the container
docker compose exec breadbox breadbox doctor

# Binary / go install: run directly
breadbox doctor
The command walks through: config load, database connection, migrations, ENCRYPTION_KEY, Plaid/Teller configuration, bank-connection credential decryption, admin account, scheduler cron expressions, and (when you’ve set a public URL) DNS + /health/ready reachability. It exits non-zero on any failure, so you can gate CI or install scripts on it.
breadbox doctor is read-only and safe to run repeatedly. It does not boot the HTTP server and does not probe Plaid or Teller with your credentials — it only validates that your env vars, database, and locally-encrypted tokens are internally consistent. To verify a Plaid/Teller connection is actually talking to the provider, trigger a sync from the admin dashboard.
Power-user flags (optional): --json emits structured output for CI scripts; --skip-external skips DNS and outbound HTTP checks for air-gapped installs.

​
After installing

Open http://your-host:8080 (or your HTTPS domain if you set one) in a browser. Breadbox redirects you to a one-time setup wizard that covers:
  • Admin account — username and password for the dashboard.
  • Bank provider — Plaid Client ID + Secret, or Teller App ID (whichever you picked above). You can skip this and fill it in later.
  • Sync interval — how often Breadbox pulls new transactions (4 / 8 / 12 / 24 hours).
  • Webhook URL (optional) — your public HTTPS host, if you have one, so Plaid and Teller can push real-time updates.
After the wizard, you’ll land in the admin dashboard ready to link your first bank. The full onboarding guide has the click-by-click walkthrough including connecting an AI agent over MCP — which is where Breadbox starts earning its keep.

Onboarding walkthrough

Connect a bank, sync your first transactions, and attach an AI agent over MCP — about 10 minutes end to end.

MCP setup

Once Breadbox is running, wire up Claude, ChatGPT, Openclaw, or any MCP-compatible agent to query your data.
Last modified on June 6, 2026