Pular para o conteúdo principal

Execute seu próprio Beancount.io com um clique

Publicado Última atualização 10 min para lerMike ThriftMike Thrift
Execute seu próprio Beancount.io com um clique
Nesta página

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

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çoO que fazCusto mensal (USD)
DashboardO web app e o único endereço público que você usaUS$ 4,90
APIGraphQL, REST, servidor MCP e o proxy GitUS$ 4,90
Serviço de ledgerValida e consulta seus livros (privado, sem endereço público)US$ 4,90
GiteaArmazena cada ledger como um repositório Git em um disco de 10 GB (privado)US$ 6,65
PostgresContas, tokens e configuraçõesUS$ 4,41
Key ValueSessões de login e cachesUS$ 7,21
TotalUS$ 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.

De um clique ao seu primeiro ledger​

  1. Inicie a stack. Clique em Deploy to bex.co (acima, ou no README), 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 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.

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

A CLI bea​

Instale ou atualize o bea via uv tool install beancount-io ou brew install bex-co/tap/bea, e então aponte-o para o seu painel:

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.

Agentes de código (MCP)​

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

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.

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

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.

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.

  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:

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 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 e pelos termos de serviço 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 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). 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).
  • 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).
  • 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.

Encontrou algum problema? Abra uma issue no GitHub ou entre no chat do Telegram.

Fonte: https://beancount.io/pt/blog/2026/11/18/run-your-own-beancount-io-from-one-button

Publicado: 18 de novembro de 2026

Última atualização: 19 de novembro de 2026