# Beancount.io mit einem Klick selbst auf bex hosten

Mit einem Klick wird der gesamte Beancount.io-Stack – das Web-Dashboard, die API und der MCP-Server, der Ledger-Dienst und deine Git-basierten Ledger – in einen bex-Workspace bereitgestellt, der dir gehört. Diese Anleitung führt vom Button bis zum funktionierenden Ledger. Danach geht es um das Verbinden deiner Tools, das Hinzufügen von Konten, das Aktualisieren, das Sichern und das Entfernen des Stacks.

Der Stack ist MIT-lizenziert, unterliegt keinen Tarifbeschränkungen und kostet etwa 33 \$ pro Monat an Hosting, abgerechnet an deinen Workspace. Die Ankündigung findest du unter [Betreibe dein eigenes Beancount.io mit einem Klick](/blog/2026/11/18/run-your-own-beancount-io-from-one-button).

## Den Stack bereitstellen

[![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)

1. **Starten.** Klicke auf **Deploy to bex.co**, wähle den Workspace, dem der Stack gehören soll, prüfe den Plan und bestätige. Bis du die Vorschau freigibst, wird nichts erstellt, und du musst nichts ausfüllen: Jedes Geheimnis wird in deinem Workspace erzeugt.
2. **Den ersten Build abwarten.** In unseren Durchläufen dauerte es 27–30 Minuten, länger, wenn die Build-Warteschlange von bex ausgelastet ist. Ein Dienst, dessen Rollout als fehlgeschlagen markiert ist, wird nicht erneut versucht; stelle diesen Dienst im bex-Dashboard erneut bereit.
3. **Deine Instanz übernehmen.** Öffne die URL des Dienstes `beancount-dashboard` und registriere dich sofort. Es gibt keinen E-Mail-Bestätigungsschritt, und die Registrierung schließt sich nach dem ersten Konto.
4. **Ein Ledger erstellen.** Beginne mit der Starter-Vorlage oder lade das Beispiel-Ledger, um dich umzusehen.

:::warning
Solange kein erstes Konto existiert, kann jeder, der die Adresse des Dashboards findet, dieses Konto anlegen. Falls sich jemand vor dir registriert, [entferne dieses Konto mit dem Admin-Token des Stacks](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), um die Registrierung wieder zu öffnen.
:::

![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)

Jedes Konto auf einem selbst gehosteten Stack bekommt den höchsten Tarif: Ledger, Direktiven, Mitwirkende und KI-Nutzung sind unbegrenzt.

## Was läuft und was es kostet

Das Blueprint erstellt sechs Ressourcen in deinem Workspace (Preise aus der Planvorschau von bex vom 18.11.2026):

| bex-Ressource | Was sie tut | Monatliche Kosten (USD) |
| --- | --- | --- |
| `beancount-dashboard` | Die Web-App und die eine öffentliche Adresse, die du verwendest | 4,90 |
| `beancount-api` | GraphQL, REST, der MCP-Server und der Git-Proxy | 4,90 |
| `beancount-ledger` | Validiert und durchsucht deine Bücher (privat, keine öffentliche Adresse) | 4,90 |
| `beancount-gitea` | Speichert jedes Ledger als Git-Repository auf einer 10-GB-Festplatte (privat) | 6,65 |
| `beancount-backend-db` | Postgres für Konten, Token und Einstellungen | 4,41 |
| `beancount-cache` | Key Value für Anmeldesitzungen und Caches | 7,21 |
| **Summe** | | **32,97** |

Ein Modellanbieter, ein Mail-Dienst oder ein S3-Bucket, den du verbindest, wird separat abgerechnet.

## Optionale Funktionen aktivieren

Der Stack startet ohne jede Integration. Eine Funktion, die eine Integration benötigt, sagt dir, welche Einstellung fehlt. Um eine hinzuzufügen, öffne den Dienst `beancount-api` in bex, füge die Variablen auf seinem Tab **Environment** hinzu und stelle den Dienst erneut bereit. Eine dort hinzugefügte Variable bleibt erhalten, wenn du das Blueprint später synchronisierst.

| Variablen | Was sie aktivieren |
| --- | --- |
| `ANTHROPIC_API_KEY` oder `OPENAI_API_KEY` | Belegscan, Kategorisierung und den Assistenten. `bea ask` benötigt `OPENAI_API_KEY`. |
| `TEMP_ASSETS_AWS_S3_*` und `PERM_ASSETS_AWS_S3_*` (`BUCKET`, `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`) | Uploads von Belegen und Anhängen |
| `SEND_GRID_API_KEY` | Mail, etwa Links zum Zurücksetzen des Passworts |
| `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` | Anmeldung über deinen eigenen Identitätsanbieter und weitere Konten (siehe **Weitere Konten hinzufügen**) |

## Deine Tools verbinden

Verwende überall die Adresse des Dashboards, außer bei Git, das die Adresse der API nutzt.

### Die bea-CLI

Installiere oder aktualisiere [`bea`](https://beancount.io/de/docs/Basics/bea-cli) mit `uv tool install beancount-io` oder `brew install bex-co/tap/bea` und richte es dann auf dein Dashboard aus:

```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
```

Beide Variablen erhalten die Adresse des Dashboards, weil das Dashboard den API-Datenverkehr weiterleitet. Die [Beancount CLI-Referenz](https://beancount.io/de/docs/bea-cli-reference) listet jeden weiteren `bea cloud`-Befehl auf.

### Coding-Agenten über MCP

Füge den MCP-Server der Bereitstellung zu Claude Code oder einem beliebigen MCP-Client hinzu:

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

Melde dich in Claude Code mit `/mcp` an. Die Zustimmungsseite wird von deiner eigenen Instanz bereitgestellt; wähle das Ledger, das der Client verwenden darf, und bestätige. Für einen Client, der stattdessen einen Header sendet, erstelle ein persönliches Zugriffstoken (siehe unten) und sende es als `Authorization: Bearer <token>`.

### Git über HTTPS

Jedes Ledger ist ein Git-Repository unter `https://<your API address>/git/<owner>/<ledger>.git`. Kopiere die exakte Adresse aus dem Menü **Git Clone** des Ledgers. bex leitet kein SSH weiter, daher läuft Git über HTTPS. Auf einem Rechner mit `bea` lässt du Git von bea anmelden:

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

Danach verlangen `git clone`, `git pull` und `git push` zu diesem Host nichts mehr, und `bea cloud logout` entfernt auch die Git-Anmeldung. `bea cloud ledger clone` klont über SSH, deshalb gibt es auf diesem Stack stattdessen die obigen Befehle aus.

![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)

### Git ohne bea

Auf einem CI-Runner oder einem Rechner ohne `bea` meldest du Git mit einem persönlichen Zugriffstoken an:

1. **Ein Token erstellen.** Öffne im Dashboard **Settings → Personal access tokens → New token**. Benenne es nach dem Ort, an dem es läuft (`laptop`, `nightly-backup`), wähle `ledger.read` zum Klonen und Pullen und füge `ledger.write` hinzu, wenn es pusht. Für ein unbeaufsichtigtes Skript beschränke es auf ein Ledger und setze ein Ablaufdatum. Kopiere das `bcio_`-Token jetzt; es wird nur einmal angezeigt.
2. **Klonen.** Git fragt nach einem Benutzernamen und einem Passwort: Gib einen beliebigen nicht leeren Benutzernamen ein und füge das Token als Passwort ein. Der macOS-Schlüsselbund und der Git Credential Manager unter Windows speichern es für das nächste Mal. Aktiviere unter Linux zuerst einen Credential-Helper, zum Beispiel `git config --global credential.helper 'cache --timeout=86400'` (für einen Tag im Speicher).

![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)

Halte das Token in einem Skript aus der Remote-URL heraus, wo Git es in `.git/config` speichern würde, und aus der Shell-Historie. Übergib es Git über einen einmaligen 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
```

Das leere `-c credential.helper=` verhindert, dass ein gespeicherter Helper das Token speichert. Übergib beide `-c`-Optionen an jedes spätere `git fetch` oder `git push` im Skript.

Wenn Git weiterhin ein altes Passwort oder ein widerrufenes Token anbietet, lösche es:

```zsh
printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject
```

### Die Mobile-App

Öffne im Willkommensbildschirm der [iOS](/beancount-ios)- oder [Android](/beancount-android)-App die Einstellungen, setze die Server-URL auf deine Dashboard-Adresse und melde dich an.

## Deine vorhandenen Bücher übernehmen

Erstelle im Dashboard ein Ledger, klone es, führe deine Dateien oder deine Git-Historie darin zusammen und pushe. Der Stack öffnet `main.bean` als Einstiegspunkt des Ledgers, benenne deine Root-Datei daher `main.bean` oder verwende `main.bean`, um deine vorhandenen Dateien per `include` einzubinden.

## Weitere Konten hinzufügen

Die Registrierung bleibt nach dem ersten Konto geschlossen. Weitere Personen kommen über einen OpenID-Connect-Anbieter hinzu, den du verbindest und der auch deren Zwei-Faktor-Anmeldung übernimmt. Auf dem Tab **Environment** des Dienstes `beancount-api`:

1. Setze `OIDC_ISSUER`, `OIDC_CLIENT_ID` und `OIDC_CLIENT_SECRET` und registriere `https://<your dashboard address>/api-gateway/auth/oidc/callback` als Redirect-URI des Clients. Die Anmeldeseite bietet dann **Sign in with** gefolgt von `OIDC_NAME` (Standard `SSO`) an.
2. Liste in `OIDC_ALLOWED_EMAILS` mit Kommas getrennt auf, wer beitreten darf: eine Adresse (`alice@example.com`), eine Domain (`@example.com`) oder deren Subdomains (`@*.example.com`). Eine aufgeführte, verifizierte Adresse erhält bei der ersten Anmeldung ein Konto und ein Standard-Ledger. Ohne die Liste meldet der Anbieter nur Konten an, die bereits damit verknüpft sind.

Alle, die du hereinlässt, teilen sich deine Festplatte und deinen Modellschlüssel, ohne Tarifbeschränkungen. Bei einem Anbieter, dem jeder beitreten kann, liste Adressen auf statt einer Domain wie `@gmail.com`.

## Ein vergessenes Passwort zurücksetzen

Ohne `SEND_GRID_API_KEY` teilt die Seite „Passwort vergessen" dem Nutzer mit, dass der Server keine E-Mail senden kann. Stelle ihm stattdessen über die Admin-API einen einmaligen Link zum Zurücksetzen aus. Kopiere `ADMIN_TOKEN` aus dem Tab **Environment** des Dienstes `beancount-api` und rufe die eigene `onbex.co`-Adresse dieses Dienstes auf, nicht die des Dashboards:

```zsh
read -rs ADMIN_TOKEN; export ADMIN_TOKEN
curl -sS -X POST "https://<your API address>/api/admin/password-reset-link" \
  -H "x-admin-token: $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'
```

Sende die zurückgegebene `resetUrl` dem Nutzer über einen Kanal, dem du vertraust. Sie funktioniert einmal und läuft nach einer Stunde ab.

:::warning
Die Admin-API ist für jeden erreichbar, der die Adresse der API erreichen kann, und allein `ADMIN_TOKEN` schützt sie. Das Token kann sich als jeder Nutzer anmelden, behandle es daher wie ein Root-Passwort: halte es aus der Shell-Historie und aus Chats heraus und rotiere es, falls es kompromittiert sein könnte.
:::

## Auf eine neuere Version aktualisieren

Der Stack bleibt auf der Version, die du bereitgestellt hast, bis du ihn aktualisierst. Ein über den Button erstelltes Blueprint erhält keinen Push-Webhook, daher erfordert eine Aktualisierung zwei Schritte:

1. **Das Blueprint synchronisieren**, um Änderungen an seinen Einstellungen anzuwenden (bex-API: `POST /v1/blueprints/<id>/sync`).
2. **Jeden Dienst am neuen Commit bereitstellen**, weil Codeänderungen einen Build erfordern (`POST /v1/services/<id>/deploys` mit `commitId`).

bex baut einen Dienst nach dem anderen, und die API zuletzt, daher kann ein vollständiger Rollout fast eine Stunde dauern. Lies, bevor du ein neueres Blueprint in einen Stack synchronisierst, der Daten enthält, [Upgrading a stack that is already running](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running) und sichere vorher.

## Sichern und Wiederherstellen

Ledger sind Git-Repositories auf der Festplatte von Gitea. Konten, persönliche Zugriffstoken und Einstellungen liegen in der verwalteten Postgres. Sichere beides jeweils auf seine eigene Weise.

### Ledger

Ein Mirror-Klon ist eine vollständige Sicherung der Dateien und der Historie eines Ledgers:

```zsh
git clone --mirror https://<your API address>/git/<owner>/<ledger>.git
```

Führe ihn auf einem Rechner aus, auf dem `bea cloud git setup` gelaufen ist, oder mit dem Token-Helper aus **Git ohne bea**. Zum Wiederherstellen lösche das Ledger im Dashboard, falls es noch aufgeführt ist, und erstelle eines mit demselben Namen. Der Server verweigert einen erzwungenen Push auf den Hauptzweig eines Ledgers, deshalb führe die Sicherung auf den ersten Commit des neuen Ledgers mit `merge` zusammen, und verwende dabei ein Token mit `ledger.write`, wenn du nicht `bea` nutzt:

```zsh
git clone https://<your API address>/git/<owner>/<ledger>.git restore
cd restore
git fetch ../<ledger>.git main
git merge --allow-unrelated-histories -X theirs -m "Restore from backup" FETCH_HEAD
git push origin HEAD
```

### Die Datenbank

bex sichert `beancount-backend-db` kontinuierlich und kann sie in einem früheren Zustand wiederherstellen. Die Wiederherstellung erfolgt immer in eine neue Datenbank, nie an Ort und Stelle, daher kopierst du diese Datenbank zurück über die des Stacks:

1. Öffne in bex `beancount-backend-db`, wähle **Recovery**, wähle einen Zeitpunkt, der mindestens zehn Minuten zurückliegt, und stelle wieder her. bex erstellt eine neue Datenbank mit den Daten zu diesem Zeitpunkt.
2. Setze `beancount-api` und `beancount-gitea` aus, damit während der Wiederherstellung nichts schreibt.
3. Kopiere die Daten mit `pg_dump` und `pg_restore` von PostgreSQL 16 zurück (das Docker-Image `postgres:16` enthält beide). Verwende für beide Enden die externe Verbindungszeichenfolge von `beancount-backend-db`, und ändere für die Kopie nur den Host auf den der Kopie. Verwende nicht die Verbindungsdaten, die bex für die Kopie anzeigt; sie nennen eine Datenbank und einen Benutzer, die die wiederhergestellten Daten nicht lesen können.

   ```zsh
   read -rs DB_URL; export DB_URL   # beancount-backend-db's external connection string
   COPY_URL="${DB_URL/@<database host>/@<copy host>}"
   pg_dump -Fc --no-owner --no-privileges "$COPY_URL" > backend.dump
   pg_restore --clean --if-exists --no-owner --no-privileges -d "$DB_URL" backend.dump
   ```

   `pg_restore` meldet, dass es die Erweiterungen `vector` und `pg_stat_statements` möglicherweise nicht löschen kann; diese Fehler sind zu erwarten. Wenn das Zertifikat der Kopie noch ausgestellt wird, füge `?sslmode=verify-full` zu `COPY_URL` hinzu und speichere die CA, die bex für die Kopie anzeigt, als `~/.postgresql/root.crt`. Wenn die Verbindung eine Zeitüberschreitung hat, versuche es erneut.
4. Setze `beancount-gitea` und `beancount-api` fort und lösche dann die Kopie.

## Was deinen Workspace verlässt

Der Stack sendet keine Analyse- oder Telemetriedaten an Beancount.io, und das Browser-Analyse-Skript wird nicht in den Build aufgenommen. Die einzigen uns bekannten ausgehenden Anfragen sind:

- **Prüfung auf kompromittierte Passwörter:** die ersten fünf Zeichen des SHA-1-Hash eines neuen Passworts, geprüft per k-Anonymität, sodass weder das Passwort noch das Konto offengelegt wird.
- **Avatare:** Der Browser fragt Gravatar nach einem Bild anhand eines Hash der E-Mail-Adresse des Nutzers.
- **Feeds:** die Feeds des Beancount.io-Blogs und des Changelogs, die nur eine Sprachpräferenz erhalten.
- **Preis-Feeds:** Anfragen an beancount.io nur, wenn ein Ledger eine verwaltete Preis-URL enthält.
- **Deine Integrationen:** alles, was du verbindest, etwa einen Modellanbieter, SendGrid, S3, Plaid oder deinen Identitätsanbieter.

Die [Datenschutztabelle in PRFAQ006](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) sagt, wann jede Anfrage ausgelöst wird. Deine Dienste, deine Festplatte und deine Datenbank laufen auf der Infrastruktur von bex, unter der [Datenschutzrichtlinie](https://bex.co/privacy-policy) und den [Nutzungsbedingungen](https://bex.co/terms-of-service) von bex. bex wird von Stargately, Inc. entwickelt, dem Unternehmen hinter Beancount.io; der gehostete Beancount.io-Dienst ist von deinem Stack getrennt und enthält keine seiner Geheimnisse.

## Den Stack entfernen

:::warning
Das Löschen der Ressourcen stoppt die Rechnung und löscht dabei deine Daten. Klone zuerst jedes Ledger.
:::

Sichere wie oben beschrieben und lösche dann die sechs Ressourcen in bex und anschließend das Blueprint. Um nur dein eigenes Konto zu entfernen und den Stack zu behalten, lösche es unter **Settings → General → Danger Zone**, wie beim [gehosteten Dienst](https://beancount.io/de/docs/request-to-delete-account); das Löschen des einzigen Kontos öffnet die Registrierung wieder.

## Lieber auf deinem eigenen Server betreiben

Die [Docker-Bereitstellung](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) betreibt denselben Stack auf einem beliebigen Server, den du kontrollierst. Die [bex-Bereitstellungshinweise](https://github.com/bex-co/beancount-io/tree/main/deploy/bex) behandeln jede Einstellung in dieser Anleitung ausführlicher.

Etwas klemmt? Erstelle ein [GitHub-Issue](https://github.com/bex-co/beancount-io/issues) oder frag im [Beancount-Telegram-Chat](https://t.me/beancount).
