# Esegui il tuo Beancount.io con un solo clic

Distribuisci l'intero stack di Beancount.io—la web app, l'API, il server MCP e i tuoi registri basati su Git—nel tuo workspace bex in circa 30 minuti. Zero configurazione, nessun limite di piano, licenza MIT e circa $33 al mese per l'hosting.



Beancount ti offre la piena proprietà delle tue finanze in testo semplice. Possedere il software attorno a quei file `.bean` è stata la parte più difficile: avere una web UI, una CLI e un endpoint per agenti AI sopra il tuo registro significava o affidare i tuoi libri contabili al nostro servizio ospitato, oppure configurare a mano sei servizi.

Da oggi, puoi avviare la tua istanza privata di Beancount.io con un solo clic.

Premi **Deploy to bex.co**, scegli il workspace che deve possedere lo stack e approva il piano. Non c'è nulla da configurare—ogni segreto viene generato automaticamente all'interno del tuo workspace. Dopo circa 30 minuti, la tua dashboard è attiva. Crea il tuo account e la registrazione si blocca alle tue spalle; nessun altro può entrare a meno che tu non lo inviti tramite il tuo identity provider.

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

Il tuo registro vive come un repository Git standard su un disco nel tuo workspace. Ogni interfaccia punta rigorosamente al tuo indirizzo, non al nostro: la dashboard web, la CLI `bea`, gli agenti di coding tramite il server MCP integrato, o il semplice `git` (per cui `bea` gestisce l'autenticazione). Non ci sono limiti di piano su registri, direttive o uso dell'AI, e lo stack non invia alcuna analitica a Beancount.io.

Le integrazioni opzionali restano disattivate finché non ne hai bisogno: porta la tua chiave del modello per la scansione delle ricevute, la categorizzazione e l'assistente; un bucket S3 per il caricamento delle ricevute; o una chiave mail per il reset della password. Finché non le aggiungi, ogni funzionalità mostra semplicemente quale impostazione richiede—tutto il resto funziona da subito.

## Cosa ottieni e quanto costa

Il deployment fornisce sei servizi fatturati direttamente al tuo workspace bex (prezzi dall'anteprima del piano di bex del 2026-11-18):

| Servizio | Cosa fa | Costo mensile (USD) |
| --- | --- | --- |
| Dashboard | La web app e l'unico indirizzo pubblico che usi | $4.90 |
| API | GraphQL, REST, server MCP e proxy Git | $4.90 |
| Servizio registro | Convalida ed esegue query sui tuoi libri contabili (privato, nessun indirizzo pubblico) | $4.90 |
| Gitea | Archivia ogni registro come repo Git su un disco da 10 GB (privato) | $6.65 |
| Postgres | Account, token e impostazioni | $4.41 |
| Key Value | Sessioni di accesso e cache | $7.21 |
| **Totale** | | **$32.97** |

Qualsiasi provider di modelli esterno, servizio mail o bucket S3 che colleghi viene fatturato separatamente da quei provider.

> **Prima di smantellare:** L'eliminazione delle risorse interrompe immediatamente la fatturazione, **e cancella i tuoi dati insieme ad essa.** Clona sempre prima i tuoi registri Git.

Ogni account su uno stack self-hosted ottiene automaticamente il livello più alto—nessun tetto artificiale:

![Impostazioni, Fatturazione su uno stack self-hosted: il piano Enterprise, con token AI, registri, direttive e collaboratori illimitati.](/img/blog/run-your-own-beancount-io-from-one-button/no-plan-limits.webp)

## Da un clic al tuo primo registro

1. **Avvia lo stack.** Clicca **Deploy to bex.co** (sopra, o nel [README](https://github.com/bex-co/beancount-io#self-host)), scegli il tuo workspace, rivedi il piano e applica. Nulla viene provisionato finché non approvi.
2. **Attendi la build iniziale.** La prima build richiede 27–30 minuti nelle nostre prove (di più se la coda di build di bex è occupata). Se un servizio mostra un rollout fallito, avvia un nuovo deployment dalla dashboard di bex.
3. **Rivendica la tua istanza.** Apri l'URL della tua dashboard e registrati immediatamente—non c'è alcun passaggio di verifica via email.
4. **Crea un registro.** Parti da zero con il template iniziale, oppure carica il registro di esempio per esplorare.

> **Nota di sicurezza:** Finché il primo account non viene creato, chiunque scopra il tuo URL può rivendicarlo. Se qualcuno ti precede, puoi [rimuovere quell'account](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) usando il token admin dello stack per riaprire la registrazione.

![Registrazione su un nuovo deployment self-hosted. Accanto al modulo, la pagina dice che questa copia è gestita dal suo proprietario e che i libri contabili sono in testo semplice in Git.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

## Punta i tuoi strumenti al tuo indirizzo

### La CLI `bea`

Installa o aggiorna [`bea`](/docs/Basics/bea-cli) tramite `uv tool install beancount-io` o `brew install bex-co/tap/bea`, poi punta alla tua dashboard:

```zsh
export BEA_API_URL=https://<indirizzo della tua dashboard>
export BEA_DASHBOARD_URL=https://<indirizzo della tua dashboard>
bea cloud login            # accede tramite il tuo browser
bea cloud ledger list
```

Entrambe le variabili d'ambiente usano lo stesso URL della dashboard, che fa da proxy per il traffico API.

![bea 0.4.1 su un deployment self-hosted: bea cloud login, bea cloud status sul piano Enterprise e bea cloud ledger list.](/img/blog/run-your-own-beancount-io-from-one-button/bea-login.webp)

### Agenti di coding (MCP)

Connetti Claude Code o qualsiasi client compatibile MCP direttamente al tuo deployment:

```zsh
claude mcp add --transport http beancount \
  https://<indirizzo della tua dashboard>/api-gateway/mcp
```

Accedi tramite `/mcp` in Claude Code—la schermata di consenso OAuth è servita dalla tua istanza. Per i client che si autenticano tramite header, genera un token in **Impostazioni → Token di accesso personale** e passalo come `Authorization: Bearer <token>`. Sul nostro stack di test, un client MCP ha immediatamente esposto 47 strumenti ed eseguito query BQL direttamente sul registro.

![Un client MCP puntato all'indirizzo del deployment con un token di accesso personale: 47 strumenti e una query BQL sul registro.](/img/blog/run-your-own-beancount-io-from-one-button/mcp-client.webp)

### Git puro

Ogni registro è un repository Git su `https://<indirizzo della tua API>/git/<owner>/<ledger>.git` (puoi copiare l'URL esatto dal menu **Git Clone** del registro). Poiché bex non instrada SSH, Git funziona su HTTPS—e `bea` gestisce le credenziali per te:

```zsh
bea cloud login            # una volta, se non l'hai già fatto
bea cloud git setup        # configura Git per autenticarsi con la tua sessione bea
git clone https://<indirizzo della tua API>/git/<owner>/<ledger>.git
```

Da lì, `git clone`, `git pull` e `git push` funzionano senza richieste di credenziali su quell'host, e `bea cloud logout` cancella anche le credenziali di Git. *(Nota: `bea cloud ledger clone` non esegue il clone direttamente su HTTPS; su server senza SSH, stampa questi comandi per te.)*

![Il menu Git Clone di un registro: l'indirizzo HTTPS dell'API, con un token di accesso personale come password.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

#### Usare Git senza `bea` (runner CI e script)

Se preferisci non installare `bea` su una macchina o un runner CI, autenticati con un token di accesso personale—proprio come su GitHub:

1. **Crea un token.** Vai in **Impostazioni → Token di accesso personale → Nuovo token**. Assegna un nome per il suo ambiente (`laptop`, `nightly-backup`), seleziona `ledger.read` per clone/pull e aggiungi `ledger.write` se deve fare push. Per script non presidiati, limitane l'ambito a un singolo registro e imposta una data di scadenza. Copia immediatamente il token `bcio_...`—viene mostrato una sola volta.

   ![Impostazioni, Token di accesso personale: un token con ledger.read e ledger.write, il suo prefisso e quando è stato creato e usato l'ultima volta.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

2. **Clona e memorizza nella cache.** Al primo clone, inserisci una stringa qualsiasi non vuota come username e incolla il token come password. macOS (Keychain) e Windows (Git Credential Manager) lo memorizzano automaticamente. Su Linux, abilita prima un credential helper: `git config --global credential.helper store` (testo semplice in `~/.git-credentials`) oppure `credential.helper 'cache --timeout=86400'` (in memoria per 24 ore).

Per script e backup pianificati, tieni il token fuori dall'URL remoto (così non viene scritto in `.git/config`) e fuori dalla cronologia della shell passando un credential helper temporaneo:

```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://<indirizzo della tua API>/git/<owner>/<ledger>.git
```

Il `-c credential.helper=` vuoto impedisce al Keychain locale o a `~/.git-credentials` di memorizzare il token. Passa entrambi i flag `-c` a ogni successivo `git fetch` o `git push` nel tuo script.

> **Risoluzione dei problemi di credenziali:** Se Git continua a ritentare con una vecchia password o un token revocato, cancellalo con `printf 'protocol=https\nhost=<indirizzo della tua API>\n\n' | git credential reject`. L'autenticazione Git basata su password funziona ancora per ora, ma sta venendo gradualmente dismessa.

**Migrare libri contabili esistenti?** Crea un nuovo registro, unisci i tuoi file o la cronologia Git e fai push. Lo stack legge `main.bean` come punto di ingresso, quindi dai al tuo file radice il nome `main.bean` oppure usalo per `include` i tuoi file esistenti.

## Cosa esce dal tuo workspace

Lo stack non invia analitiche o telemetria a Beancount.io, e lo script di analitica del browser è completamente rimosso dalla build. Le uniche richieste in uscita che conosciamo sono:

- **Controllo delle password compromesse:** I primi 5 caratteri dell'hash SHA-1 di una nuova password vengono verificati tramite k-anonymity (né la tua password né il tuo account vengono esposti).
- **Avatar:** Richieste del browser a Gravatar usando un hash dell'indirizzo email dell'utente.
- **Feed:** Richieste per i feed del blog e del changelog di Beancount.io (invia solo una preferenza di lingua, nessun dato utente).
- **Feed dei prezzi:** Richieste a beancount.io *solo* se il tuo registro include esplicitamente un URL di prezzi gestito.
- **Le tue integrazioni:** Dati inviati ai servizi a cui scegli di aderire (provider LLM, SendGrid, S3, Plaid o il tuo provider OIDC).

Vedi la [tabella completa sulla privacy](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) per i dettagli esatti su quando ciascuna richiesta viene effettuata.

## Chi gestisce le macchine

I tuoi servizi, il tuo disco e il tuo database girano sull'infrastruttura di bex, all'interno del tuo workspace e sulla tua fattura. Piena trasparenza: bex è realizzato da Stargately, Inc.—la stessa azienda dietro Beancount.io—e l'hosting è regolato dalla [privacy policy](https://bex.co/privacy-policy) e dai [termini di servizio](https://bex.co/terms-of-service) di bex. Il servizio Beancount.io ospitato è completamente separato dal tuo stack e non conserva nessuno dei suoi segreti.

Preferisci eseguire su hardware che controlli direttamente? Il nostro [deployment Docker](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) esegue lo stesso identico stack su qualsiasi server di tua proprietà.

## Da sapere

- **Utente singolo per impostazione predefinita, OIDC per team o famiglia.** La registrazione si chiude dopo la creazione del primo account. Per aggiungere altri, collega un provider OpenID Connect e elenca gli indirizzi consentiti in `OIDC_ALLOWED_EMAILS` ([guida alla configurazione](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#more-accounts-your-own-identity-provider)). Il 2FA è gestito dal tuo identity provider.
- **Aggiornamenti secondo i tuoi tempi.** Il tuo stack resta bloccato alla versione che hai distribuito finché non scegli di sincronizzare il Blueprint e ridistribuire ([come aggiornare](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#rolling-out-a-change)).
- **Backup semplici.** I registri sono solo repo Git—`git clone --mirror` esegue il backup dell'intera cronologia. Account, token e impostazioni risiedono in Postgres gestito con backup continui e point-in-time recovery ([guida al backup](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#back-up-and-restore)).
- **Supporto app mobile.** Nella schermata di benvenuto dell'app mobile, apri le impostazioni, punta l'URL del server all'indirizzo della tua dashboard e accedi.

Per ogni passaggio in un unico posto, inclusi aggiornamenti, backup, reset delle password e rimozione dello stack, vedi la [guida al self-hosting](/docs/self-host-beancount-io).

Hai incontrato un intoppo? Apri una [issue su GitHub](https://github.com/bex-co/beancount-io/issues) o entra nella [chat Telegram](https://t.me/beancount).
