Met één klik wordt de volledige Beancount.io-stack geïmplementeerd — inclusief het webdashboard, de API en MCP-server, de grootboekdienst en je door Git ondersteunde grootboeken — in een bex-workspace die je bezit. Deze handleiding gaat van de knop naar een werkend grootboek. Daarna behandelt het verbinden van je tools, het toevoegen van accounts, bijwerken, back-uppen en het verwijderen van de stack.
De stack heeft een MIT-licentie, kent geen abonnementslimieten en kost ongeveer $33 per maand aan hosting, gefactureerd aan je workspace. Lees de aankondiging in Start je eigen Beancount.io met één klik.
De stack implementeren
- Start het. Druk op Deploy to bex.co, kies de workspace die de stack moet bezitten, bekijk het plan en pas het toe. Er wordt niets aangemaakt totdat je de preview goedkeurt, en er hoeft niets te worden ingevuld: elk geheim wordt binnen je workspace gegenereerd.
- Wacht op de eerste build. Dit duurde in onze tests 27–30 minuten, en langer wanneer de buildwachtrij van bex druk is. Een dienst waarvan de rollout als mislukt is gemarkeerd, wordt niet opnieuw geprobeerd; implementeer die dienst opnieuw vanuit het bex-dashboard.
- Claim je instantie. Open de URL van de
beancount-dashboard-dienst en meld je direct aan. Er is geen stap voor e-mailverificatie, en de aanmelding sluit zodra het eerste account bestaat. - Maak een grootboek. Begin met de startersjabloon, of laad het voorbeeldgrootboek om rond te kijken.
Zolang het eerste account nog niet bestaat, kan iedereen die het adres van het dashboard vindt, het aanmaken. Als iemand zich vóór jou aanmeldt, verwijder dat account dan met het admin-token van de stack om de aanmelding weer te openen.

Elk account op een self-hosted stack krijgt het hoogste niveau: grootboeken, directives, medewerkers en AI-gebruik zijn onbeperkt.
Wat er draait en wat het kost
De Blueprint maakt zes resources aan in je workspace (prijzen uit de plan-preview van bex op 2026-11-18):
| bex-resource | Wat het doet | Maandelijkse kosten (USD) |
|---|---|---|
beancount-dashboard | De webapp, en het enige openbare adres dat je gebruikt | 4.90 |
beancount-api | GraphQL, REST, de MCP-server en de Git-proxy | 4.90 |
beancount-ledger | Valideert en doorzoekt je boeken (privé, geen openbaar adres) | 4.90 |
beancount-gitea | Slaat elk grootboek op als Git-repository op een schijf van 10 GB (privé) | 6.65 |
beancount-backend-db | Postgres voor accounts, tokens en instellingen | 4.41 |
beancount-cache | Key Value voor aanmeldsessies en caches | 7.21 |
| Totaal | 32.97 |
Een modelprovider, maildienst of S3-bucket die je verbindt, wordt apart gefactureerd.
Optionele functies inschakelen
De stack start zonder enige integratie. Een functie die er een nodig heeft, meldt welke instelling ontbreekt. Om er een toe te voegen, open je de beancount-api-dienst in bex, voeg je de variabelen toe op het tabblad Environment en implementeer je de dienst opnieuw. Een variabele die je daar toevoegt, blijft behouden wanneer je de Blueprint later synchroniseert.
| Variabelen | Wat ze inschakelen |
|---|---|
ANTHROPIC_API_KEY of OPENAI_API_KEY | Bonnetjes scannen, categoriseren en de assistent. bea ask vereist OPENAI_API_KEY. |
TEMP_ASSETS_AWS_S3_* en PERM_ASSETS_AWS_S3_* (BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY) | Uploads van bonnetjes en bijlagen |
SEND_GRID_API_KEY | Mail, zoals links voor het resetten van wachtwoorden |
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET | Aanmelden via je eigen identiteitsprovider, en meer accounts (zie Meer accounts toevoegen) |
Je tools verbinden
Gebruik overal het adres van het dashboard, behalve voor Git; dat gebruikt het adres van de API.
De bea CLI
Installeer of update bea met uv tool install beancount-io of brew install bex-co/tap/bea, en wijs het naar je dashboard:
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 variabelen gebruiken het adres van het dashboard, omdat het dashboard API-verkeer doorstuurt. De Beancount CLI-referentie vermeldt elk ander bea cloud-commando.
Codeeragents via MCP
Voeg de MCP-server van de implementatie toe aan Claude Code of een andere MCP-client:
claude mcp add --transport http beancount \
https://<your dashboard address>/api-gateway/mcpMeld je aan met /mcp in Claude Code. De toestemmingspagina wordt geserveerd door je eigen instantie; kies het grootboek dat de client mag gebruiken en keur het goed. Voor een client die in plaats daarvan een header verstuurt, maak je een persoonlijk toegangstoken aan (hieronder) en verstuur je dat als Authorization: Bearer <token>.
Git over HTTPS
Elk grootboek is een Git-repository op https://<your API address>/git/<owner>/<ledger>.git. Kopieer het exacte adres uit het menu Git Clone van het grootboek. bex routeert geen SSH, dus Git werkt via HTTPS. Laat Git op een machine met bea aanmelden via:
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>.gitDaarna vragen git clone, git pull en git push naar die host om niets meer, en bea cloud logout verwijdert ook de Git-aanmelding. bea cloud ledger clone kloont via SSH en drukt op deze stack daarom de bovenstaande commando's af.

Git zonder bea
Op een CI-runner of een machine zonder bea meld je Git aan met een persoonlijk toegangstoken:
- Maak een token aan. Open in het dashboard Settings → Personal access tokens → New token. Geef het een naam die past bij waar het draait (
laptop,nightly-backup), kiesledger.readom te klonen en pullen, en voegledger.writetoe als het pusht. Beperk het voor een onbeheerd script tot één grootboek en stel een vervaldatum in. Kopieer nu hetbcio_-token; het wordt maar één keer getoond. - Kloon. Git vraagt om een gebruikersnaam en een wachtwoord: voer een willekeurige niet-lege gebruikersnaam in en plak het token als wachtwoord. macOS Keychain en Git Credential Manager op Windows bewaren het voor de volgende keer. Schakel op Linux eerst een credential helper in, bijvoorbeeld
git config --global credential.helper 'cache --timeout=86400'(een dag in het geheugen).

Houd het token in een script buiten de remote-URL, waar Git het in .git/config zou opslaan, en buiten de shellgeschiedenis. Geef het aan Git via een eenmalige 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>.gitDe lege -c credential.helper= voorkomt dat een opgeslagen helper het token bewaart. Geef beide -c-opties mee aan elke latere git fetch of git push in het script.
Als Git blijft vragen om een oud wachtwoord of een ingetrokken token, wis het dan:
printf 'protocol=https\nhost=<your API address>\n\n' | git credential rejectDe mobiele app
Open op het welkomstscherm van de iOS- of Android-app de instellingen, stel de server-URL in op je dashboardadres en meld je aan.
Je bestaande boeken meenemen
Maak een grootboek aan in het dashboard, kloon het, voeg je bestanden of je Git-geschiedenis erin samen en push. De stack opent main.bean als het ingangspunt van het grootboek, dus noem je hoofd辣bestand main.bean of gebruik main.bean om je bestaande bestanden te include-en.
Meer accounts toevoegen
De aanmelding blijft gesloten na het eerste account. Meer mensen sluiten zich aan via een OpenID Connect-provider die je verbindt, die ook hun tweestapsaanmelding afhandelt. Op het tabblad Environment van de beancount-api-dienst:
- Stel
OIDC_ISSUER,OIDC_CLIENT_IDenOIDC_CLIENT_SECRETin en registreerhttps://<your dashboard address>/api-gateway/auth/oidc/callbackals de redirect-URI van de client. De aanmeldpagina biedt dan Sign in with gevolgd doorOIDC_NAME(standaardSSO). - Vermeld wie mag joinen in
OIDC_ALLOWED_EMAILS, gescheiden door komma's: een adres ([email protected]), een domein (@example.com) of de subdomeinen ervan (@*.example.com). Een vermeld, geverifieerd adres krijgt bij de eerste aanmelding een account en een standaardgrootboek. Zonder de lijst meldt de provider alleen accounts aan die er al aan gekoppeld zijn.
Iedereen die je toelaat, deelt je schijf en modelsleutel, zonder abonnementslimieten. Met een provider waar iedereen kan joinen, vermeld je adressen in plaats van een domein zoals @gmail.com.
Een vergeten wachtwoord resetten
Zonder SEND_GRID_API_KEY meldt de pagina voor vergeten wachtwoorden de gebruiker dat de server geen e-mail kan versturen. Geef hun in plaats daarvan een eenmalige resetlink uit de admin-API. Kopieer ADMIN_TOKEN van het tabblad Environment van de beancount-api-dienst en gebruik het eigen onbex.co-adres van die dienst, niet dat van het dashboard:
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]"}'Stuur de teruggegeven resetUrl naar de gebruiker via een kanaal dat je vertrouwt. Deze werkt één keer en verloopt na een uur.
De admin-API is bereikbaar voor iedereen die het adres van de API kan bereiken, en alleen ADMIN_TOKEN beveiligt hem. Het token kan zich als elke gebruiker aanmelden, dus behandel het als een root-wachtwoord: houd het buiten de shellgeschiedenis en chat, en roteer het als het mogelijk is uitgelekt.
Bijwerken naar een nieuwere release
De stack blijft op de versie die je hebt geïmplementeerd totdat je hem bijwerkt. Een Blueprint die via de knop is aangemaakt, krijgt geen push-webhook, dus een update kost twee stappen:
- Synchroniseer de Blueprint om wijzigingen in de instellingen toe te passen (bex API:
POST /v1/blueprints/<id>/sync). - Implementeer elke dienst op de nieuwe commit, omdat codewijzigingen een build vereisen (
POST /v1/services/<id>/deploysmetcommitId).
bex bouwt één dienst tegelijk en de API bouwt als laatste, dus een volledige rollout kan bijna een uur duren. Lees voordat je een nieuwere Blueprint synchroniseert in een stack die gegevens bevat Een al draaiende stack upgraden en maak eerst een back-up.
Back-uppen en herstellen
Grootboeken zijn Git-repositories op de schijf van Gitea. Accounts, persoonlijke toegangstokens en instellingen staan in de beheerde Postgres. Maak van elk op zijn eigen manier een back-up.
Grootboeken
Een mirror-clone is een volledige back-up van de bestanden en geschiedenis van een grootboek:
git clone --mirror https://<your API address>/git/<owner>/<ledger>.gitVoer dit uit op een machine waar bea cloud git setup is uitgevoerd, of met de token-helper uit Git zonder bea. Om te herstellen, verwijder je het grootboek in het dashboard als het nog in de lijst staat en maak je een nieuw aan met dezelfde naam. De server weigert een geforceerde push naar de hoofdtak van een grootboek, dus voeg je de back-up samen bovenop de eerste commit van het nieuwe grootboek, met een token met ledger.write als je geen bea gebruikt:
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 HEADDe database
bex maakt continu back-ups van beancount-backend-db en kan deze herstellen zoals die er op een eerder tijdstip uitzag. Het herstelt naar een nieuwe database, nooit ter plaatse, dus je kopieert die database terug over die van de stack zelf:
-
Open in bex
beancount-backend-db, kies Recovery, kies een tijdstip van ten minste tien minuten geleden en herstel. bex maakt een nieuwe database aan met de gegevens van dat tijdstip. -
Schort
beancount-apienbeancount-giteaop, zodat er niets schrijft terwijl je herstelt. -
Kopieer de gegevens terug met
pg_dumpenpg_restorevan PostgreSQL 16 (de Docker-imagepostgres:16heeft beide). Gebruik de externe verbindingsstring vanbeancount-backend-dbvoor beide kanten, en wijzig voor de kopie alleen de host naar die van de kopie. Gebruik niet de verbindingsgegevens die bex voor de kopie toont; die noemen een database en een gebruiker die de herstelde gegevens niet kunnen lezen.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_restoremeldt dat het de extensiesvectorenpg_stat_statementsmogelijk niet kan verwijderen; die fouten zijn te verwachten. Als het certificaat van de kopie nog wordt uitgegeven, voeg dan?sslmode=verify-fulltoe aanCOPY_URLen sla de CA die bex voor de kopie toont op als~/.postgresql/root.crt. Als de verbinding een time-out geeft, probeer het dan opnieuw. -
Hervat
beancount-giteaenbeancount-apien verwijder daarna de kopie.
Wat je workspace verlaat
De stack verstuurt geen analytics of telemetrie naar Beancount.io, en het analytics-script van de browser wordt niet in de build opgenomen. De enige uitgaande verzoeken die we kennen, zijn:
- Controles op gecompromitteerde wachtwoorden: de eerste vijf tekens van de SHA-1-hash van een nieuw wachtwoord, gecontroleerd via k-anonimiteit, zodat noch het wachtwoord noch het account wordt onthuld.
- Avatars: de browser vraagt Gravatar om een afbeelding op basis van een hash van het e-mailadres van de gebruiker.
- Feeds: de blog- en changelog-feeds van Beancount.io, die alleen een taalvoorkeur ontvangen.
- Prijsfeeds: verzoeken aan beancount.io, alleen wanneer een grootboek een beheerde prijs-URL bevat.
- Je integraties: alles wat je verbindt, zoals een modelprovider, SendGrid, S3, Plaid of je identiteitsprovider.
De privacytabel in PRFAQ006 vermeldt wanneer elk verzoek plaatsvindt. Je diensten, schijf en database draaien op de infrastructuur van bex, onder het privacybeleid en de servicevoorwaarden van bex. bex is gebouwd door Stargately, Inc., het bedrijf achter Beancount.io; de gehoste Beancount.io-dienst staat los van je stack en bevat geen van zijn geheimen.
De stack verwijderen
Het verwijderen van de resources stopt de factuur en verwijdert je gegevens mee. Kloon eerst elk grootboek.
Maak een back-up zoals hierboven beschreven en verwijder daarna de zes resources in bex, gevolgd door de Blueprint. Om alleen je eigen account te verwijderen en de stack te behouden, verwijder je het onder Settings → General → Danger Zone, zoals op de gehoste dienst; door het enige account te verwijderen, wordt de aanmelding weer geopend.
In plaats daarvan op je eigen server draaien
De Docker-implementatie draait dezelfde stack op elke server die je beheert. De bex-implementatienotities behandelen elke instelling in deze handleiding dieper.
Loop je ergens tegenaan? Open een GitHub-issue of vraag het in de Beancount Telegram-chat.