Zum Hauptinhalt springen

Beancount.io mit einem Klick selbst auf bex hosten

Stelle Beancount.io mit einem Klick in deinem eigenen bex-Workspace bereit, verbinde dann bea, MCP-Clients, Git und die Mobile-App, füge Konten hinzu und sichere deine Daten.

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​

Deploy to bex.co

  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.
Warnung

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.

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.

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-RessourceWas sie tutMonatliche Kosten (USD)
beancount-dashboardDie Web-App und die eine öffentliche Adresse, die du verwendest4,90
beancount-apiGraphQL, REST, der MCP-Server und der Git-Proxy4,90
beancount-ledgerValidiert und durchsucht deine Bücher (privat, keine öffentliche Adresse)4,90
beancount-giteaSpeichert jedes Ledger als Git-Repository auf einer 10-GB-Festplatte (privat)6,65
beancount-backend-dbPostgres für Konten, Token und Einstellungen4,41
beancount-cacheKey Value für Anmeldesitzungen und Caches7,21
Summe32,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.

VariablenWas sie aktivieren
ANTHROPIC_API_KEY oder OPENAI_API_KEYBelegscan, 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_KEYMail, etwa Links zum Zurücksetzen des Passworts
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRETAnmeldung ü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 list

Beide 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/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:

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.

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.

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>.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:

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

Die 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:

  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 ([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.

Warnung

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 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>.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:

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.

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

Warnung

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.

Quelle: https://beancount.io/de/docs/self-host-beancount-io