Un clic distribuisce l'intero stack di Beancount.io, inclusi la dashboard web, l'API e il server MCP, il servizio ledger e i tuoi ledger su Git, in un workspace bex di tua proprietà. Questa guida va dal pulsante a un ledger funzionante. Poi copre il collegamento dei tuoi strumenti, l'aggiunta di account, l'aggiornamento, il backup e la rimozione dello stack.
Lo stack è distribuito con licenza MIT, non applica limiti di piano e costa circa $33 al mese di hosting, addebitati al tuo workspace. Per l'annuncio, leggi Esegui il tuo Beancount.io con un solo clic.
Distribuisci lo stack
- Avvialo. Premi Deploy to bex.co, scegli il workspace a cui deve appartenere lo stack, rivedi il piano e applica. Nulla viene creato finché non approvi l'anteprima, e non c'è nulla da compilare: ogni secret viene generato all'interno del tuo workspace.
- Attendi la prima build. Nei nostri test ha richiesto 27–30 minuti, e di più quando la coda di build di bex è occupata. Un servizio il cui rollout è contrassegnato come fallito non viene ritentato; distribuisci di nuovo quel servizio dalla dashboard di bex.
- Rivendica la tua istanza. Apri l'URL del servizio
beancount-dashboarde registrati subito. Non c'è alcun passaggio di verifica via email, e la registrazione si chiude dietro il primo account. - Crea un ledger. Parti dal template iniziale, oppure carica il ledger di esempio per dare un'occhiata.
Finché il primo account non esiste, chiunque trovi l'indirizzo della dashboard può crearlo. Se qualcuno si registra prima di te, rimuovi quell'account con il token admin dello stack per riaprire la registrazione.

Ogni account su uno stack self-hosted ottiene il livello massimo: ledger, direttive, collaboratori e utilizzo dell'AI sono illimitati.
Cosa viene eseguito e quanto costa
Il Blueprint crea sei risorse nel tuo workspace (prezzi dall'anteprima del piano di bex del 2026-11-18):
| Risorsa bex | Cosa fa | Costo mensile (USD) |
|---|---|---|
beancount-dashboard | L'app web, e l'unico indirizzo pubblico che usi | 4.90 |
beancount-api | GraphQL, REST, il server MCP e il proxy Git | 4.90 |
beancount-ledger | Convalida ed esegue query sui tuoi libri (privato, nessun indirizzo pubblico) | 4.90 |
beancount-gitea | Memorizza ogni ledger come repository Git su un disco da 10 GB (privato) | 6.65 |
beancount-backend-db | Postgres per account, token e impostazioni | 4.41 |
beancount-cache | Key Value per sessioni di accesso e cache | 7.21 |
| Totale | 32.97 |
Un provider di modelli, un servizio di posta o un bucket S3 che colleghi vengono addebitati separatamente.
Attiva le funzionalità opzionali
Lo stack si avvia senza alcuna integrazione. Una funzionalità che ne richiede una indica quale impostazione manca. Per aggiungerne una, apri il servizio beancount-api in bex, aggiungi le variabili nella sua scheda Environment e distribuisci di nuovo il servizio. Una variabile che aggiungi lì viene mantenuta quando successivamente sincronizzi il Blueprint.
| Variabili | Cosa attivano |
|---|---|
ANTHROPIC_API_KEY o OPENAI_API_KEY | Scansione delle ricevute, categorizzazione e l'assistente. bea ask richiede OPENAI_API_KEY. |
TEMP_ASSETS_AWS_S3_* e PERM_ASSETS_AWS_S3_* (BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY) | Caricamento di ricevute e allegati |
SEND_GRID_API_KEY | Posta, come i link di reimpostazione della password |
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET | Accesso tramite il tuo provider di identità, e più account (vedi Aggiungi altri account) |
Collega i tuoi strumenti
Usa l'indirizzo della dashboard ovunque, tranne per Git, che usa l'indirizzo dell'API.
La CLI bea
Installa o aggiorna bea con uv tool install beancount-io o brew install bex-co/tap/bea, poi puntalo alla tua 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 listEntrambe le variabili prendono l'indirizzo della dashboard, perché la dashboard inoltra il traffico dell'API. Il riferimento della CLI di Beancount elenca ogni altro comando bea cloud.
Agenti di coding tramite MCP
Aggiungi il server MCP della distribuzione a Claude Code o a qualsiasi client MCP:
claude mcp add --transport http beancount \
https://<your dashboard address>/api-gateway/mcpAccedi con /mcp in Claude Code. La pagina di consenso è servita dalla tua istanza; scegli il ledger che il client può usare e approva. Per un client che invia invece un header, crea un personal access token (sotto) e invialo come Authorization: Bearer <token>.
Git su HTTPS
Ogni ledger è un repository Git su https://<your API address>/git/<owner>/<ledger>.git. Copia l'indirizzo esatto dal menu Git Clone del ledger. bex non instrada SSH, quindi Git funziona su HTTPS. Su una macchina con bea, lascia che sia bea ad autenticare Git:
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>.gitDopo di che, git clone, git pull e git push verso quell'host non chiedono nulla, e bea cloud logout rimuove anche l'accesso di Git. bea cloud ledger clone clona via SSH, quindi su questo stack stampa invece i comandi qui sopra.

Git senza bea
Su un runner CI o su una macchina senza bea, autentica Git con un personal access token:
- Crea un token. Nella dashboard, apri Settings → Personal access tokens → New token. Assegnagli un nome in base a dove viene eseguito (
laptop,nightly-backup), scegliledger.readper clonare e fare pull, e aggiungiledger.writese effettua push. Per uno script non presidiato, limitarlo a un solo ledger e imposta una scadenza. Copia subito il tokenbcio_; viene mostrato solo una volta. - Clona. Git chiede un nome utente e una password: inserisci un nome utente qualsiasi non vuoto e incolla il token come password. Il Keychain di macOS e Git Credential Manager su Windows lo conservano per la volta successiva. Su Linux, abilita prima un credential helper, ad esempio
git config --global credential.helper 'cache --timeout=86400'(in memoria per un giorno).

In uno script, tieni il token fuori dall'URL del remote, dove Git lo salverebbe in .git/config, e fuori dalla cronologia della shell. Passalo a Git tramite un credential helper temporaneo:
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>.gitIl -c credential.helper= vuoto impedisce a un helper memorizzato di salvare il token. Passa entrambe le opzioni -c a ogni successivo git fetch o git push nello script.
Se Git continua a proporre una vecchia password o un token revocato, cancellalo:
printf 'protocol=https\nhost=<your API address>\n\n' | git credential rejectL'app mobile
Nella schermata di benvenuto dell'app iOS o Android, apri le impostazioni, imposta l'URL del server all'indirizzo della tua dashboard e accedi.
Importa i tuoi libri esistenti
Crea un ledger nella dashboard, clonalo, unisci i tuoi file o la tua cronologia Git al suo interno, e fai push. Lo stack apre main.bean come punto di ingresso del ledger, quindi chiama il tuo file radice main.bean oppure usa main.bean per fare include dei tuoi file esistenti.
Aggiungi altri account
La registrazione resta chiusa dopo il primo account. Altre persone si uniscono tramite un provider OpenID Connect che colleghi, che gestisce anche il loro accesso a due fattori. Nella scheda Environment del servizio beancount-api:
- Imposta
OIDC_ISSUER,OIDC_CLIENT_IDeOIDC_CLIENT_SECRET, e registrahttps://<your dashboard address>/api-gateway/auth/oidc/callbackcome redirect URI del client. La pagina di accesso offre quindi Sign in with seguito daOIDC_NAME(predefinitoSSO). - Elenca chi può unirsi in
OIDC_ALLOWED_EMAILS, separati da virgole: un indirizzo ([email protected]), un dominio (@example.com), o i suoi sottodomini (@*.example.com). Un indirizzo verificato e presente nell'elenco ottiene un account e un ledger predefinito la prima volta che accede. Senza l'elenco, il provider autentica solo gli account già collegati ad esso.
Chiunque tu lasci entrare condivide il tuo disco e la chiave del modello, senza limiti di piano. Con un provider a cui chiunque può unirsi, elenca indirizzi anziché un dominio come @gmail.com.
Reimposta una password dimenticata
Senza SEND_GRID_API_KEY, la pagina di password dimenticata comunica all'utente che il server non può inviare email. Emetti invece per loro un link di reimpostazione monouso dall'API admin. Copia ADMIN_TOKEN dalla scheda Environment del servizio beancount-api, e chiama l'indirizzo onbex.co di quel servizio, non quello della 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]"}'Invia il resetUrl restituito all'utente tramite un canale di cui ti fidi. Funziona una sola volta e scade dopo un'ora.
L'API admin è raggiungibile da chiunque possa raggiungere l'indirizzo dell'API, ed è protetta solo da ADMIN_TOKEN. Il token può accedere come qualsiasi utente, quindi trattalo come una password di root: tienilo fuori dalla cronologia della shell e dalle chat, e ruotalo se potrebbe essere trapelato.
Aggiorna a una versione più recente
Lo stack resta alla versione che hai distribuito finché non lo aggiorni. Un Blueprint creato dal pulsante non riceve un webhook di push, quindi un aggiornamento richiede due passaggi:
- Sincronizza il Blueprint per applicare le modifiche alle sue impostazioni (API di bex:
POST /v1/blueprints/<id>/sync). - Distribuisci ogni servizio al nuovo commit, perché le modifiche al codice richiedono una build (
POST /v1/services/<id>/deploysconcommitId).
bex costruisce un servizio alla volta e l'API per ultima, quindi un rollout completo può richiedere quasi un'ora. Prima di sincronizzare un Blueprint più recente in uno stack che contiene dati, leggi Aggiornare uno stack già in esecuzione ed esegui prima il backup.
Backup e ripristino
I ledger sono repository Git sul disco di Gitea. Account, personal access token e impostazioni risiedono nel Postgres gestito. Esegui il backup di ciascuno a modo suo.
I ledger
Un clone mirror è un backup completo dei file e della cronologia di un ledger:
git clone --mirror https://<your API address>/git/<owner>/<ledger>.gitEseguilo su una macchina dove è stato eseguito bea cloud git setup, oppure con l'helper dei token di Git senza bea. Per ripristinare, elimina il ledger nella dashboard se è ancora elencato e creane uno con lo stesso nome. Il server rifiuta un push forzato al branch principale di un ledger, quindi unisci il backup sopra il primo commit del nuovo ledger, usando un token con ledger.write quando non usi bea:
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 HEADIl database
bex esegue il backup di beancount-backend-db in modo continuo e può ripristinarlo com'era in un momento precedente. Il ripristino avviene in un nuovo database, mai sul posto, quindi copi quel database sopra quello dello stack:
-
In bex, apri
beancount-backend-db, scegli Recovery, seleziona un momento di almeno dieci minuti fa e ripristina. bex crea un nuovo database con i dati a quel momento. -
Sospendi
beancount-apiebeancount-gitea, così nulla scrive durante il ripristino. -
Copia i dati indietro con
pg_dumpepg_restoredi PostgreSQL 16 (l'immagine Dockerpostgres:16li contiene entrambi). Usa la stringa di connessione esterna dibeancount-backend-dbper entrambe le estremità, e per la copia cambia solo l'host con quello della copia. Non usare i dettagli di connessione che bex mostra per la copia; indicano un database e un utente che non possono leggere i dati ripristinati.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_restoresegnala che potrebbe non riuscire a eliminare le estensionivectorepg_stat_statements; quegli errori sono previsti. Se il certificato della copia è ancora in fase di emissione, aggiungi?sslmode=verify-fullaCOPY_URLe salva la CA che bex mostra per la copia come~/.postgresql/root.crt. Se la connessione va in timeout, riprova. -
Riprendi
beancount-giteaebeancount-api, poi elimina la copia.
Cosa esce dal tuo workspace
Lo stack non invia analytics o telemetria a Beancount.io, e lo script di analytics del browser è escluso dalla build. Le uniche richieste in uscita di cui siamo a conoscenza sono:
- Controllo delle password violate: i primi cinque caratteri dell'hash SHA-1 della nuova password, verificati tramite k-anonymity, così né la password né l'account vengono rivelati.
- Avatar: il browser chiede a Gravatar un'immagine tramite un hash dell'indirizzo email dell'utente.
- Feed: i feed del blog e del changelog di Beancount.io, che ricevono solo una preferenza di lingua.
- Feed dei prezzi: richieste a beancount.io solo quando un ledger include un URL di prezzi gestito.
- Le tue integrazioni: qualunque cosa tu colleghi, come un provider di modelli, SendGrid, S3, Plaid o il tuo provider di identità.
La tabella sulla privacy in PRFAQ006 indica quando viene effettuata ciascuna richiesta. I tuoi servizi, il disco e il database vengono eseguiti sull'infrastruttura di bex, secondo la politica sulla privacy e i termini di servizio di bex. bex è sviluppato da Stargately, Inc., l'azienda dietro Beancount.io; il servizio Beancount.io ospitato è separato dal tuo stack e non custodisce nessuno dei suoi secret.
Rimuovi lo stack
Eliminare le risorse ferma la fatturazione e cancella i tuoi dati insieme ad esse. Clona prima ogni ledger.
Esegui il backup come descritto sopra, poi elimina le sei risorse in bex, seguite dal Blueprint. Per rimuovere solo il tuo account e mantenere lo stack, eliminalo in Settings → General → Danger Zone, come sul servizio ospitato; eliminare l'unico account riapre la registrazione.
Eseguilo invece sul tuo server
La distribuzione Docker esegue lo stesso stack su qualsiasi server tu controlli. Le note sulla distribuzione bex trattano in modo più approfondito ogni impostazione di questa guida.
Hai incontrato un problema? Apri una issue su GitHub o chiedi nella chat Telegram di Beancount.