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.
Den Stack bereitstellen
- 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.
- 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.
- Deine Instanz übernehmen. Öffne die URL des Dienstes
beancount-dashboardund registriere dich sofort. Es gibt keinen E-Mail-Bestätigungsschritt, und die Registrierung schließt sich nach dem ersten Konto. - Ein Ledger erstellen. Beginne mit der Starter-Vorlage oder lade das Beispiel-Ledger, um dich umzusehen.
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, um die Registrierung wieder zu öffnen.

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 mit uv tool install beancount-io oder brew install bex-co/tap/bea und richte es dann auf dein Dashboard aus:
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 listBeide Variablen erhalten die Adresse des Dashboards, weil das Dashboard den API-Datenverkehr weiterleitet. Die Beancount CLI-Referenz 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:
claude mcp add --transport http beancount \
https://<your dashboard address>/api-gateway/mcpMelde 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:
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>.gitDanach 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.

Git ohne bea
Auf einem CI-Runner oder einem Rechner ohne bea meldest du Git mit einem persönlichen Zugriffstoken an:
- 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ähleledger.readzum Klonen und Pullen und fügeledger.writehinzu, wenn es pusht. Für ein unbeaufsichtigtes Skript beschränke es auf ein Ledger und setze ein Ablaufdatum. Kopiere dasbcio_-Token jetzt; es wird nur einmal angezeigt. - 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).

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:
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>.gitDas 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:
printf 'protocol=https\nhost=<your API address>\n\n' | git credential rejectDie Mobile-App
Öffne im Willkommensbildschirm der iOS- oder 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:
- Setze
OIDC_ISSUER,OIDC_CLIENT_IDundOIDC_CLIENT_SECRETund registrierehttps://<your dashboard address>/api-gateway/auth/oidc/callbackals Redirect-URI des Clients. Die Anmeldeseite bietet dann Sign in with gefolgt vonOIDC_NAME(StandardSSO) an. - Liste in
OIDC_ALLOWED_EMAILSmit Kommas getrennt auf, wer beitreten darf: eine Adresse ([email protected]), 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:
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":"[email protected]"}'Sende die zurückgegebene resetUrl dem Nutzer über einen Kanal, dem du vertraust. Sie funktioniert einmal und läuft nach einer Stunde ab.
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:
- Das Blueprint synchronisieren, um Änderungen an seinen Einstellungen anzuwenden (bex-API:
POST /v1/blueprints/<id>/sync). - Jeden Dienst am neuen Commit bereitstellen, weil Codeänderungen einen Build erfordern (
POST /v1/services/<id>/deploysmitcommitId).
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 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:
git clone --mirror https://<your API address>/git/<owner>/<ledger>.gitFü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:
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 HEADDie 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:
-
Ö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. -
Setze
beancount-apiundbeancount-giteaaus, damit während der Wiederherstellung nichts schreibt. -
Kopiere die Daten mit
pg_dumpundpg_restorevon PostgreSQL 16 zurück (das Docker-Imagepostgres:16enthält beide). Verwende für beide Enden die externe Verbindungszeichenfolge vonbeancount-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.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.dumppg_restoremeldet, dass es die Erweiterungenvectorundpg_stat_statementsmöglicherweise nicht löschen kann; diese Fehler sind zu erwarten. Wenn das Zertifikat der Kopie noch ausgestellt wird, füge?sslmode=verify-fullzuCOPY_URLhinzu 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. -
Setze
beancount-giteaundbeancount-apifort 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 sagt, wann jede Anfrage ausgelöst wird. Deine Dienste, deine Festplatte und deine Datenbank laufen auf der Infrastruktur von bex, unter der Datenschutzrichtlinie und den Nutzungsbedingungen 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
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; das Löschen des einzigen Kontos öffnet die Registrierung wieder.
Lieber auf deinem eigenen Server betreiben
Die Docker-Bereitstellung betreibt denselben Stack auf einem beliebigen Server, den du kontrollierst. Die bex-Bereitstellungshinweise behandeln jede Einstellung in dieser Anleitung ausführlicher.
Etwas klemmt? Erstelle ein GitHub-Issue oder frag im Beancount-Telegram-Chat.