> ## Documentation Index
> Fetch the complete documentation index at: https://breadbox-mintlify-7401d007.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard your Breadbox instance

> After you've installed Breadbox, use this guide to run the first-run wizard, connect your first bank, and hook up an AI agent.

Onboarding picks up where [installation](/installation) leaves off — this guide assumes Breadbox is already running and reachable at a URL you know (either a public HTTPS host per [Remote Hosting](/installation/remote-hosting) or `http://localhost:8080` for a local eval). If you haven't installed yet, start with [Install Breadbox](/installation).

By the end of this guide you'll have completed the first-run setup wizard, linked a bank account, watched the initial sync complete, and attached an AI agent over <Tooltip headline="Model Context Protocol" tip="The open standard for giving AI agents structured access to tools and data." cta="Read the MCP spec" href="https://modelcontextprotocol.io">MCP</Tooltip>.

## Step 1: Open the setup wizard

Open your Breadbox URL in a browser. On first launch Breadbox redirects you to the setup wizard automatically — the wizard runs once and collects everything needed before you can link a bank.

## Step 2: Complete the wizard

The wizard has five sub-steps. Work through them in order:

<Steps>
  <Step title="Create your admin account">
    Enter a username and password. This is the account you'll use to log in to the dashboard and manage connections.
  </Step>

  <Step title="Configure a bank provider">
    You can do this later from the dashboard, but setting it up now lets you link a bank immediately.

    * **Teller (recommended starter):** enter your **App ID** from the [Teller console](https://teller.io/) and the path to your client certificate and private key. Teller's Development tier is free and works with real bank data — no production approval process, which makes it the fastest way to verify the setup end-to-end.
    * **Plaid:** paste your **Client ID** and **Secret** from the [Plaid dashboard](https://dashboard.plaid.com/). Use the Sandbox environment for simulated data or Production once you're approved.
  </Step>

  <Step title="Set the sync interval">
    Pick how often Breadbox polls your banks for new transactions. The default is 12 hours. You can change it at any time from the admin dashboard.
  </Step>

  <Step title="Set your webhook URL">
    Enter the public URL of your Breadbox instance (e.g., `https://your-breadbox.example.com`). Plaid and Teller deliver real-time webhooks to `https://<your-host>/webhooks/<provider>` so transactions show up in seconds instead of on the polling interval.

    You can leave this blank temporarily if your public URL isn't set up yet — polling-only sync works without it. Come back and fill it in once remote hosting is live.
  </Step>

  <Step title="Finish">
    Review your settings and click **Complete setup**. Breadbox saves your configuration and drops you into the admin dashboard.
  </Step>
</Steps>

## Step 3: Link your first bank

From the dashboard, go to **Connections → Add connection**. Pick the family member this account belongs to, choose your provider, and complete the Plaid Link or Teller Connect flow in the browser popup.

Your bank credentials go directly to Plaid or Teller — Breadbox never sees them. Once you finish the popup, Breadbox stores the encrypted access token and queues an initial sync.

If your household has multiple family members, add them from **Settings → Users** (or via the [Users API](/api/overview)) before linking additional banks so each connection can be attributed to the right person.

## Step 4: Wait for the initial sync

The first sync pulls up to two years of transaction history. Most connections finish in under a minute; accounts with long histories take longer. Watch the **Connections** page — the status transitions from `in_progress` to `success` when the sync completes.

If you see an `error` status instead, open the connection to view the provider error message and retry.

## Step 5: Connect your first AI agent

This is where Breadbox earns its keep. Point your AI app at Breadbox's `/mcp` endpoint and it can query accounts, search transactions, categorize, tag, and summarize spending — all against your live data, without ever touching your bank credentials.

<Steps>
  <Step title="Generate an API key">
    In the dashboard, go to **Settings → API Keys** and click **Create API Key**. Start with a **read-only** scope for your first agent — it limits blast radius while you verify the integration works. You can issue a full-access key later for agents that need to categorize or trigger syncs.

    Copy the key immediately — Breadbox only shows it once.
  </Step>

  <Step title="Configure your agent">
    Pick your client from the [MCP setup guide](/mcp/setup) — Claude (Desktop / web / mobile), Claude Code, ChatGPT, Codex, Openclaw, Manus, and any other MCP-compatible client are covered there. Paste your Breadbox URL and API key into the config.
  </Step>

  <Step title="Ask something">
    Start a conversation and ask the agent something only Breadbox would know:

    > "How much did we spend on groceries last month, and what are the top three merchants?"

    If the agent comes back with numbers that match your dashboard, the connection is live.
  </Step>
</Steps>

For ready-made agent workflows — automated weekly reviews, subscription tracking, cross-referencing Gmail receipts — see the [Guides](/guides/overview) tab.

## Step 6 (optional): Query the REST API

If you prefer to script against Breadbox from your own tools, the REST API mirrors the MCP surface. A minimal sanity-check query:

```bash theme={null}
curl -H "X-API-Key: bb_your_api_key" \
  "https://your-breadbox.example.com/api/v1/transactions?limit=5"
```

Replace the host and key with your own. Full endpoint reference lives under [API](/api/overview).

## What's next?

<Columns cols={2}>
  <Card title="MCP setup" icon="bot" href="/mcp/setup">
    Detailed walk-throughs per AI client, including Claude, ChatGPT, Openclaw, and Codex.
  </Card>

  <Card title="Guides" icon="book-open" href="/guides/overview">
    End-to-end agent workflows: weekly reviews, subscription tracking, Gmail cross-referencing.
  </Card>

  <Card title="Transaction rules" icon="filter" href="/transactions/rules">
    Auto-categorize transactions with flexible AND/OR/NOT rule conditions.
  </Card>

  <Card title="Bank connections" icon="landmark" href="/connections/overview">
    Add more banks, manage existing connections, or import CSV files.
  </Card>
</Columns>