# Execute seu próprio Beancount.io com um clique

Implante toda a stack do Beancount.io — o web app, a API, o servidor MCP e seus ledgers com Git — no seu próprio workspace bex em cerca de 30 minutos. Zero configuração, sem limites de plano, com licença MIT e aproximadamente US$ 33/mês em hospedagem.



O Beancount oferece a você o controle total das suas finanças em texto puro. Controlar o software em torno desses arquivos `.bean` tem sido mais difícil: obter uma interface web, uma CLI e um endpoint de agente de IA sobre o seu ledger significava ou confiar seus livros ao nosso serviço hospedado, ou configurar seis serviços manualmente.

A partir de hoje, você pode criar sua própria instância privada do Beancount.io com um único clique.

Clique em **Deploy to bex.co**, escolha o workspace que deve ser o proprietário da stack e aprove o plano. Não há nada para configurar — cada segredo é gerado automaticamente dentro do seu workspace. Cerca de 30 minutos depois, seu painel está no ar. Crie sua conta, e o cadastro se fecha atrás de você; ninguém mais consegue entrar, a menos que você os convide pelo seu próprio provedor de identidade.

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

Seu ledger fica em um repositório Git padrão em um disco no seu workspace. Todas as interfaces apontam estritamente para o seu endereço, não para o nosso: o painel web, a CLI `bea`, agentes de código via o servidor MCP integrado, ou `git` puro (para o qual o `bea` faz a autenticação por você). Não há limites de plano para ledgers, diretivas ou uso de IA, e a stack não envia nenhum dado de análise para o Beancount.io.

As integrações opcionais ficam desligadas até você precisar delas: use sua própria chave de modelo para leitura de recibos, categorização e o assistente; um bucket S3 para envio de recibos; ou uma chave de e-mail para redefinição de senha. Até você adicioná-las, cada recurso simplesmente mostra qual configuração ele precisa — todo o resto funciona pronto para uso.

## O que você recebe e quanto custa

A implantação provisiona seis serviços cobrados diretamente no seu workspace bex (preços da prévia de plano do bex em 2026-11-18):

| Serviço | O que faz | Custo mensal (USD) |
| --- | --- | --- |
| Dashboard | O web app e o único endereço público que você usa | US$ 4,90 |
| API | GraphQL, REST, servidor MCP e o proxy Git | US$ 4,90 |
| Serviço de ledger | Valida e consulta seus livros (privado, sem endereço público) | US$ 4,90 |
| Gitea | Armazena cada ledger como um repositório Git em um disco de 10 GB (privado) | US$ 6,65 |
| Postgres | Contas, tokens e configurações | US$ 4,41 |
| Key Value | Sessões de login e caches | US$ 7,21 |
| **Total** | | **US$ 32,97** |

Qualquer provedor de modelo externo, serviço de e-mail ou bucket S3 que você conectar é cobrado separadamente por esses provedores.

> **Antes de destruir tudo:** Excluir os recursos interrompe a cobrança imediatamente, **e apaga seus dados junto.** Sempre clone seus ledgers Git primeiro.

Toda conta em uma stack auto-hospedada recebe automaticamente o nível mais alto — sem tetos artificiais:

![Configurações, Faturamento em uma stack auto-hospedada: o plano Enterprise, com tokens de IA, ledgers, diretivas e colaboradores ilimitados.](/img/blog/run-your-own-beancount-io-from-one-button/no-plan-limits.webp)

## De um clique ao seu primeiro ledger

1. **Inicie a stack.** Clique em **Deploy to bex.co** (acima, ou no [README](https://github.com/bex-co/beancount-io#self-host)), escolha seu workspace, revise o plano e aplique. Nada é provisionado até você aprovar.
2. **Aguarde a build inicial.** A primeira build leva de 27 a 30 minutos nas nossas execuções (mais se a fila de build do bex estiver ocupada). Se um serviço apresentar falha na implantação, dispare uma nova implantação pelo painel do bex.
3. **Reivindique sua instância.** Abra a URL do seu painel e cadastre-se imediatamente — não há etapa de verificação por e-mail.
4. **Crie um ledger.** Comece do zero com o modelo inicial ou carregue o ledger de exemplo para explorar.

> **Nota de segurança:** Até a primeira conta ser criada, qualquer pessoa que descobrir sua URL pode reivindicá-la. Se alguém chegar antes de você, é possível [remover essa conta](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 o token de administrador da stack para reabrir o cadastro.

![Cadastro em uma nova implantação auto-hospedada. Ao lado do formulário, a página diz que esta cópia é executada pelo seu proprietário e os livros são texto puro no Git.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

## Aponte suas ferramentas para o seu próprio endereço

### A CLI `bea`

Instale ou atualize o [`bea`](/docs/Basics/bea-cli) via `uv tool install beancount-io` ou `brew install bex-co/tap/bea`, e então aponte-o para o seu painel:

```zsh
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
```

Ambas as variáveis de ambiente usam a mesma URL do painel, que faz proxy do tráfego da API para você.

![bea 0.4.1 contra uma implantação auto-hospedada: bea cloud login, bea cloud status no plano Enterprise e bea cloud ledger list.](/img/blog/run-your-own-beancount-io-from-one-button/bea-login.webp)

### Agentes de código (MCP)

Conecte o Claude Code ou qualquer cliente compatível com MCP diretamente à sua implantação:

```zsh
claude mcp add --transport http beancount \
  https://<your dashboard address>/api-gateway/mcp
```

Faça login via `/mcp` no Claude Code — a tela de consentimento OAuth é servida pela sua própria instância. Para clientes que autenticam via cabeçalhos, gere um token em **Configurações → Tokens de acesso pessoal** e passe-o como `Authorization: Bearer <token>`. Na nossa stack de teste, um cliente MCP expôs imediatamente 47 ferramentas e executou consultas BQL diretamente no ledger.

![Um cliente MCP apontado para o endereço da própria implantação com um token de acesso pessoal: 47 ferramentas e uma consulta BQL sobre o ledger.](/img/blog/run-your-own-beancount-io-from-one-button/mcp-client.webp)

### Git puro

Cada ledger é um repositório Git em `https://<your API address>/git/<owner>/<ledger>.git` (você pode copiar a URL exata no menu **Git Clone** do ledger). Como o bex não roteia SSH, o Git funciona via HTTPS — e o `bea` cuida das credenciais para você:

```zsh
bea cloud login            # once, if you haven't already
bea cloud git setup        # configures Git to authenticate with your bea session
git clone https://<your API address>/git/<owner>/<ledger>.git
```

A partir daí, `git clone`, `git pull` e `git push` funcionam sem pedir credenciais naquele host, e `bea cloud logout` também limpa as credenciais do Git. *(Nota: `bea cloud ledger clone` não clona diretamente via HTTPS; em servidores sem SSH, ele imprime esses comandos para você.)*

![O menu Git Clone de um ledger: o endereço HTTPS da API, com um token de acesso pessoal como senha.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

#### Usando Git sem o `bea` (runners de CI e scripts)

Se você preferir não instalar o `bea` em uma máquina ou runner de CI, autentique-se com um token de acesso pessoal — assim como no GitHub:

1. **Crie um token.** Vá em **Configurações → Tokens de acesso pessoal → Novo token**. Dê um nome para o ambiente (`laptop`, `nightly-backup`), selecione `ledger.read` para clonar/atualizar e adicione `ledger.write` se ele precisar fazer push. Para scripts não assistidos, restrinja-o a um único ledger e defina uma data de expiração. Copie o token `bcio_...` imediatamente — ele é exibido apenas uma vez.

   ![Configurações, Tokens de acesso pessoal: um token com ledger.read e ledger.write, seu prefixo, e quando foi criado e usado pela última vez.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

2. **Clone e armazene em cache.** No seu primeiro clone, insira qualquer string não vazia como nome de usuário e cole o token como senha. macOS (Keychain) e Windows (Git Credential Manager) armazenam automaticamente. No Linux, habilite um credential helper primeiro: `git config --global credential.helper store` (texto puro em `~/.git-credentials`) ou `credential.helper 'cache --timeout=86400'` (em memória por 24 horas).

Para scripts e backups agendados, mantenha o token fora da URL remota (para não ser gravado em `.git/config`) e fora do histórico do shell passando um credential helper avulso:

```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://<your API address>/git/<owner>/<ledger>.git
```

O `-c credential.helper=` vazio impede que o Keychain local ou `~/.git-credentials` armazene o token em cache. Passe ambas as flags `-c` para qualquer `git fetch` ou `git push` subsequente no seu script.

> **Solução de problemas de credenciais:** Se o Git continuar tentando uma senha antiga ou token revogado, limpe-o com `printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject`. A autenticação Git por senha ainda funciona por enquanto, mas está sendo descontinuada.

**Migrando livros existentes?** Crie um novo ledger, mescle seus arquivos ou histórico Git nele e faça push. A stack lê `main.bean` como ponto de entrada, então nomeie seu arquivo raiz como `main.bean` ou use-o para `include` seus arquivos existentes.

## O que sai do seu workspace

A stack não envia nenhuma análise ou telemetria para o Beancount.io, e o script de análise do navegador é removido completamente da build. As únicas requisições externas que conhecemos são:

- **Verificação de vazamento de senhas:** Os primeiros 5 caracteres do hash SHA-1 de uma nova senha são verificados via k-anonimato (nem sua senha nem sua conta são expostas).
- **Avatares:** Requisições do navegador ao Gravatar usando um hash do endereço de e-mail do usuário.
- **Feeds:** Requisições para os feeds do blog e changelog do Beancount.io (envia apenas uma preferência de idioma, nenhum dado de usuário).
- **Feeds de preços:** Requisições ao beancount.io *apenas* se seu ledger incluir explicitamente uma URL de preço gerenciada.
- **Suas próprias integrações:** Dados enviados para serviços que você optar por usar (provedores de LLM, SendGrid, S3, Plaid ou seu provedor OIDC).

Veja a [tabela completa de privacidade](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) para detalhes exatos sobre quando cada requisição é disparada.

## Quem opera as máquinas

Seus serviços, disco e banco de dados rodam na infraestrutura do bex, dentro do seu workspace e na sua conta. Transparência total: o bex é construído pela Stargately, Inc. — a mesma empresa por trás do Beancount.io — e a hospedagem é regida pela [política de privacidade](https://bex.co/privacy-policy) e pelos [termos de serviço](https://bex.co/terms-of-service) do bex. O serviço hospedado do Beancount.io é completamente separado da sua stack e não possui nenhum dos seus segredos.

Prefere rodar em hardware que você controla diretamente? Nossa [implantação Docker](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) executa exatamente a mesma stack em qualquer servidor que você possuir.

## Bom saber

- **Usuário único por padrão, OIDC para equipes ou família.** O cadastro fecha após a criação da primeira conta. Para adicionar outras pessoas, conecte um provedor OpenID Connect e liste os endereços permitidos em `OIDC_ALLOWED_EMAILS` ([guia de configuração](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#more-accounts-your-own-identity-provider)). O 2FA é tratado pelo seu provedor de identidade.
- **Atualizações no seu ritmo.** Sua stack permanece fixada na versão que você implantou até você optar por sincronizar o Blueprint e reimplantar ([como atualizar](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#rolling-out-a-change)).
- **Backups simples.** Os ledgers são apenas repositórios Git — `git clone --mirror` faz backup de todo o seu histórico. Contas, tokens e configurações ficam no Postgres gerenciado com backups contínuos e recuperação point-in-time ([guia de backup](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#back-up-and-restore)).
- **Suporte ao app móvel.** Na tela de boas-vindas do app móvel, abra as configurações, aponte a URL do servidor para o endereço do seu painel e faça login.

Para todos os passos em um só lugar, incluindo atualizações, backups, redefinições de senha e remoção da stack, consulte o [guia de auto-hospedagem](/docs/self-host-beancount-io).

Encontrou algum problema? Abra uma [issue no GitHub](https://github.com/bex-co/beancount-io/issues) ou entre no [chat do Telegram](https://t.me/beancount).
