# Run your own Beancount.io with one click

Deploy the entire Beancount.io stack—the web app, API, MCP server, and your Git-backed ledgers—into your own bex workspace in about 30 minutes. Zero configuration, no plan limits, MIT-licensed, and roughly $33/month in hosting.



Beancount gives you full ownership of your finances in plain text. Owning the software around those `.bean` files has been harder: getting a web UI, CLI, and AI agent endpoint on top of your ledger meant either trusting our hosted service with your books or wiring up six services by hand.

Starting today, you can spin up your own private Beancount.io instance with a single click.

Press **Deploy to bex.co**, choose the workspace that should own the stack, and approve the plan. There is nothing to configure—every secret is generated automatically inside your workspace. About 30 minutes later, your dashboard is live. Create your account, and sign-up locks behind you; nobody else can get in unless you invite them through your own identity provider.

[![Deploy to bex.co](/img/blog/run-your-own-beancount-io-from-one-button/deploy-to-bex.svg)](https://dashboard.bex.co/deploy?repo=https://github.com/bex-co/beancount-io&path=bex.yaml)

Your ledger lives as a standard Git repository on a disk in your workspace. Every interface points strictly to your address, not ours: the web dashboard, the `bea` CLI, coding agents via the built-in MCP server, or plain `git` (which `bea` authenticates for you). There are no plan limits on ledgers, directives, or AI usage, and the stack sends zero analytics back to Beancount.io.

Optional integrations stay off until you need them: bring your own model key for receipt scanning, categorization, and the assistant; an S3 bucket for receipt uploads; or a mail key for password resets. Until you add them, each feature simply shows which setting it needs—everything else works out of the box.

## What you get, and what it costs

The deployment provisions six services billed directly to your bex workspace (prices from bex's plan preview on 2026-11-18):

| Service | What it does | Monthly cost (USD) |
| --- | --- | --- |
| Dashboard | The web app and the single public address you use | $4.90 |
| API | GraphQL, REST, MCP server, and the Git proxy | $4.90 |
| Ledger service | Validates and queries your books (private, no public address) | $4.90 |
| Gitea | Stores each ledger as a Git repo on a 10 GB disk (private) | $6.65 |
| Postgres | Accounts, tokens, and settings | $4.41 |
| Key Value | Sign-in sessions and caches | $7.21 |
| **Total** | | **$32.97** |

Any external model provider, mail service, or S3 bucket you connect is billed separately by those providers.

> **Before you tear it down:** Deleting the resources stops the bill immediately, **and deletes your data with it.** Always clone your Git ledgers first.

Every account on a self-hosted stack gets the top tier automatically—no artificial ceilings:

![Settings, Billing on a self-hosted stack: the Enterprise plan, with AI tokens, ledgers, directives and collaborators unlimited.](/img/blog/run-your-own-beancount-io-from-one-button/no-plan-limits.webp)

## From one click to your first ledger

1. **Launch the stack.** Click **Deploy to bex.co** (above, or in the [README](https://github.com/bex-co/beancount-io#self-host)), pick your workspace, review the plan, and apply. Nothing is provisioned until you approve it.
2. **Wait for the initial build.** The first build takes 27–30 minutes in our runs (longer if bex's build queue is busy). If a service shows a failed rollout, trigger a redeploy from the bex dashboard.
3. **Claim your instance.** Open your dashboard URL and sign up immediately—there is no email verification step.
4. **Create a ledger.** Start fresh from the starter template, or load the sample ledger to explore.

> **Security note:** Until the first account is created, anyone who discovers your URL can claim it. If someone beats you to it, you can [remove that account](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#13-someone-signed-up-before-me-what-now) using the stack's admin token to reopen sign-up.

![Sign-up on a new self-hosted deployment. Beside the form, the page says this copy is run by its owner and the books are plain text in Git.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

## Point your tools at your own address

### The `bea` CLI

Install or update [`bea`](/docs/Basics/bea-cli) via `uv tool install beancount-io` or `brew install bex-co/tap/bea`, then point it at your dashboard:

```zsh
export BEA_API_URL=https://<your dashboard address>
export BEA_DASHBOARD_URL=https://<your dashboard address>
bea cloud login            # signs in through your browser
bea cloud ledger list
```

Both environment variables use the same dashboard URL, which proxies API traffic for you.

![bea 0.4.1 against a self-hosted deployment: bea cloud login, bea cloud status on the Enterprise plan, and bea cloud ledger list.](/img/blog/run-your-own-beancount-io-from-one-button/bea-login.webp)

### Coding agents (MCP)

Connect Claude Code or any MCP-compatible client directly to your deployment:

```zsh
claude mcp add --transport http beancount \
  https://<your dashboard address>/api-gateway/mcp
```

Sign in via `/mcp` in Claude Code—the OAuth consent screen is served by your own instance. For clients that authenticate via headers instead, generate a token under **Settings → Personal access tokens** and pass it as `Authorization: Bearer <token>`. On our test stack, an MCP client immediately exposed 47 tools and ran BQL queries straight against the ledger.

![An MCP client pointed at the deployment's own address with a personal access token: 47 tools, and a BQL query over the ledger.](/img/blog/run-your-own-beancount-io-from-one-button/mcp-client.webp)

### Plain Git

Every ledger is a Git repository at `https://<your API address>/git/<owner>/<ledger>.git` (you can copy the exact URL from the ledger's **Git Clone** menu). Because bex doesn't route SSH, Git runs over HTTPS—and `bea` handles the credentials for you:

```zsh
bea cloud login            # once, if you haven't already
bea cloud git setup        # configures Git to authenticate with your bea session
git clone https://<your API address>/git/<owner>/<ledger>.git
```

From there, `git clone`, `git pull`, and `git push` work without prompting on that host, and `bea cloud logout` clears Git's credentials too. *(Note: `bea cloud ledger clone` doesn't clone over HTTPS directly; on servers without SSH, it prints these commands for you.)*

![A ledger's Git Clone menu: the API's HTTPS address, with a personal access token as the password.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

#### Using Git without `bea` (CI runners & scripts)

If you'd rather not install `bea` on a machine or CI runner, authenticate with a personal access token—just like GitHub:

1. **Create a token.** Go to **Settings → Personal access tokens → New token**. Name it for its environment (`laptop`, `nightly-backup`), select `ledger.read` for cloning/pulling, and add `ledger.write` if it needs to push. For unattended scripts, scope it to a single ledger and set an expiration date. Copy the `bcio_...` token immediately—it is only shown once.

   ![Settings, Personal access tokens: a token with ledger.read and ledger.write, its prefix, and when it was created and last used.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

2. **Clone and cache.** On your first clone, enter any non-empty string as the username and paste the token as the password. macOS (Keychain) and Windows (Git Credential Manager) store it automatically. On Linux, enable a credential helper first: `git config --global credential.helper store` (plain text in `~/.git-credentials`) or `credential.helper 'cache --timeout=86400'` (in memory for 24 hours).

For scripts and scheduled backups, keep the token out of the remote URL (so it isn't written to `.git/config`) and out of your shell history by passing a one-off credential helper:

```zsh
read -rs BEANCOUNT_TOKEN; export BEANCOUNT_TOKEN
helper='!f() { echo username=token; echo "password=$BEANCOUNT_TOKEN"; }; f'
git -c credential.helper= -c credential.helper="$helper" \
  clone --mirror https://<your API address>/git/<owner>/<ledger>.git
```

The empty `-c credential.helper=` prevents your local Keychain or `~/.git-credentials` from caching the token. Pass both `-c` flags to any subsequent `git fetch` or `git push` in your script.

> **Troubleshooting credentials:** If Git keeps retrying an old password or revoked token, clear it with `printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject`. Password-based Git auth still works for now, but it is being phased out.

**Migrating existing books?** Create a new ledger, merge your files or Git history into it, and push. The stack reads `main.bean` as the entry point, so either name your root file `main.bean` or use it to `include` your existing files.

## What leaves your workspace

The stack sends no analytics or telemetry to Beancount.io, and the browser analytics script is stripped from the build entirely. The only outbound requests we know of are:

- **Password breach checks:** The first 5 characters of a new password's SHA-1 hash are checked via k-anonymity (neither your password nor your account is exposed).
- **Avatars:** Browser requests to Gravatar using a hash of the user's email address.
- **Feeds:** Requests for the Beancount.io blog and changelog feeds (sends only a language preference, no user data).
- **Price feeds:** Requests to beancount.io *only* if your ledger explicitly includes a managed price URL.
- **Your own integrations:** Data sent to services you opt into (LLM providers, SendGrid, S3, Plaid, or your OIDC provider).

See the [full privacy table](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) for exact details on when each request fires.

## Who runs the machines

Your services, disk, and database run on bex's infrastructure, inside your workspace and on your bill. Full transparency: bex is built by Stargately, Inc.—the same company behind Beancount.io—and hosting is governed by bex's [privacy policy](https://bex.co/privacy-policy) and [terms of service](https://bex.co/terms-of-service). The hosted Beancount.io service is completely separate from your stack and holds none of its secrets.

Prefer to run on hardware you control directly? Our [Docker deployment](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) runs the exact same stack on any server you own.

## Good to know

- **Single-user by default, OIDC for teams or family.** Sign-up closes after the first account is created. To add others, connect an OpenID Connect provider and list allowed addresses in `OIDC_ALLOWED_EMAILS` ([setup guide](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#more-accounts-your-own-identity-provider)). 2FA is handled by your identity provider.
- **Updates on your schedule.** Your stack stays pinned to the version you deployed until you choose to sync the Blueprint and redeploy ([how to update](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#rolling-out-a-change)).
- **Straightforward backups.** Ledgers are just Git repos—`git clone --mirror` backs up your entire history. Accounts, tokens, and settings live in managed Postgres with continuous backups and point-in-time recovery ([backup guide](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#back-up-and-restore)).
- **Mobile app support.** On the mobile app's welcome screen, open settings, point the server URL to your dashboard address, and sign in.

For every step in one place, including updates, backups, password resets, and removing the stack, see the [self-hosting guide](/docs/self-host-beancount-io).

Hit a snag? Open a [GitHub issue](https://github.com/bex-co/beancount-io/issues) or drop into the [Telegram chat](https://t.me/beancount).
