Um único clique implanta toda a pilha do Beancount.io, incluindo o painel web, a API e o servidor MCP, o serviço de livro-razão (ledger) e seus livros-razão baseados em Git, em um espaço de trabalho bex de sua propriedade. Este guia vai do botão a um livro-razão funcional. Em seguida, ele cobre a conexão de suas ferramentas, adição de contas, atualização, backup e remoção da pilha.
A pilha tem licença MIT, não aplica limites de plano e custa cerca de US$ 33 por mês em hospedagem, faturado no seu espaço de trabalho. Para o anúncio, leia Execute seu próprio Beancount.io com um clique.
Implante a pilha
- Lance-o. Pressione Deploy to bex.co (Implantar no bex.co), escolha o espaço de trabalho que deve ser o proprietário da pilha, revise o plano e aplique. Nada é criado até que você aprove a prévia, e não há nada para preencher: todos os segredos são gerados dentro do seu espaço de trabalho.
- Aguardar a primeira compilação. Levou de 27 a 30 minutos em nossos testes, e mais tempo quando a fila de compilação do bex está ocupada. Um serviço cujo lançamento esteja marcado como falhou não é retentado; implante esse serviço novamente a partir do painel do bex.
- Reivindique sua instância. Abra a URL do serviço
beancount-dashboarde cadastre-se imediatamente. Não há etapa de verificação de e-mail, e o registro fecha após a primeira conta. - Crie um livro-razão. Comece pelo modelo inicial ou carregue o livro-razão de exemplo para dar uma olhada.
Até que a primeira conta exista, qualquer pessoa que encontre o endereço do painel pode criá-la. Se alguém se cadastrar antes de você, remova essa conta usando o token de administrador da pilha para reabrir o cadastro.

Toda conta em uma pilha auto-hospedada recebe o nível superior: livros-razão, diretivas, colaboradores e uso de IA são ilimitados.
O que funciona e qual o custo
O Blueprint cria seis recursos em seu espaço de trabalho (preços da prévia do plano do bex em 2026-11-18):
| recurso bex | O que faz | Custo mensal (USD) |
|---|---|---|
beancount-dashboard | O aplicativo web e o endereço público que você usa | 4.90 |
beancount-api | GraphQL, REST, o servidor MCP e o proxy Git | 4.90 |
beancount-ledger | Valida e consulta seus livros (privado, sem endereço público) | 4.90 |
beancount-gitea | Armazena cada livro-razão como um repositório Git em um disco de 10 GB (privado) | 6.65 |
beancount-backend-db | Postgres para contas, tokens e configurações | 4.41 |
beancount-cache | Key Value para sessões de login e caches | 7.21 |
| Total | 32.97 |
Um provedor de modelos, serviço de e-mail ou bucket S3 que você conectar cobrará separadamente.
Ative recursos opcionais
A pilha inicia sem nenhuma integração. Um recurso que precisa de algo indica qual configuração está faltando. Para adicionar um, abra o serviço beancount-api no bex, adicione as variáveis na aba Environment (Ambiente) e implante o serviço novamente. Uma variável que você adiciona lá é mantida quando sincroniza o Blueprint mais tarde.
| Variáveis | O que elas ativam |
|---|---|
ANTHROPIC_API_KEY ou OPENAI_API_KEY | Digitalização de recibos, categorização e o assistente. O bea ask precisa de OPENAI_API_KEY. |
TEMP_ASSETS_AWS_S3_* e PERM_ASSETS_AWS_S3_* (BUCKET, ACCESS_KEY_ID, SECRET_ACCESS_KEY) | Upload de recibos e anexos |
SEND_GRID_API_KEY | E-mail, como links de redefinição de senha |
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET | Login através do seu próprio provedor de identidade e mais contas (veja Adicionar mais contas) |
Conecte suas ferramentas
Use o endereço do painel em todos os lugares, exceto para o Git, que usa o endereço da API.
A CLI do bea
Instale ou atualize bea com uv tool install beancount-io ou brew install bex-co/tap/bea, depois aponte-o para o seu painel:
export BEA_API_URL=https://<seu endereço do dashboard>
export BEA_DASHBOARD_URL=https://<seu endereço do dashboard>
bea cloud login # faz login através do seu navegador
bea cloud ledger listAmbas as variáveis usam o endereço do dashboard, porque o dashboard encaminha o tráfego da API. A referência da CLI Beancount lista todos os outros comandos bea cloud.
Agentes de codificação via MCP
Adicione o servidor MCP da implantação ao Claude Code ou a qualquer cliente MCP:
claude mcp add --transport http beancount \
https://<seu endereço do dashboard>/api-gateway/mcpFaça login com /mcp no Claude Code. A página de consentimento é servida pela sua própria instância; escolha o livro-razão que o cliente pode usar e aprove. Para um cliente que envia um cabeçalho em vez disso, crie um token de acesso pessoal (abaixo) e envie-o como Authorization: Bearer <token>.
Git via HTTPS
Cada livro-razão é um repositório Git em https://<seu endereço da API>/git/<dono>/<ledger>.git. Copie o endereço exato do menu Git Clone do livro-razão. O bex não roteia SSH, então o Git é executado via HTTPS. Em uma máquina com bea, deixe-o fazer login no Git:
bea cloud login # uma vez, se ainda não o fez
bea cloud git setup # Agora o Git faz login com sua sessão bea
git clone https://<seu endereço da API>/git/<dono>/<ledger>.gitDepois disso, git clone, git pull e git push para esse host não pedem nada, e bea cloud logout remove o login do Git. O bea cloud ledger clone clona via SSH, então nesta pilha ele imprime os comandos acima em vez disso.

Git sem bea
Em um executor CI ou em uma máquina sem bea, faça login no Git com um token de acesso pessoal:
- Crie um token. No painel, abra Settings → Personal access tokens → New token. Dê um nome para onde será executado (
laptop,backup-diário), escolhaledger.readpara clonar e puxar, e adicioneledger.writese fizer push. Para um script sem acompanhamento, limite a um livro-razão e defina um prazo de validade. Copie o tokenbcio_agora; ele é mostrado apenas uma vez. - Clone. O Git solicita um nome de usuário e uma senha: insira qualquer nome de usuário não vazio e cole o token como senha. O macOS Keychain e o Git Credential Manager no Windows guardam-no para a próxima vez. No Linux, ative um helper de credencial primeiro, por exemplo
git config --global credential.helper 'cache --timeout=86400'(na memória por um dia).

Em um script, mantenha o token fora da URL remota, onde o Git o salvaria em .git/config, e fora do histórico do shell. Passe-o ao Git através de um helper de credencial único:
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://<seu endereço da API>/git/<dono>/<ledger>.gitO -c credential.helper= vazio impede que um helper armazenado salve o token. Passe ambos os argumentos -c a cada git fetch ou git push posterior no script.
Se o Git continuar oferecendo uma senha antiga ou um token revogado, limpe-o:
printf 'protocol=https\nhost=<seu endereço da API>\n\n' | git credential rejectO aplicativo móvel
Na tela de boas-vindas do aplicativo iOS ou Android, abra as configurações, defina a URL do servidor para o endereço do seu painel e faça login.
Trazer seus livros existentes
Crie um livro-razão no painel, clone-o, mescle seus arquivos ou seu histórico Git nele e envie (push). A pilha abre main.bean como o ponto de entrada do livro-razão, então nomeie seu arquivo raiz como main.bean ou use main.bean para include seus arquivos existentes.
Adicionar mais contas
O cadastro permanece fechado após a primeira conta. Mais pessoas entram por meio de um provedor OpenID Connect que você conecta, o qual também lida com a autenticação de dois fatores delas. Na aba Environment do serviço beancount-api:
- Defina
OIDC_ISSUER,OIDC_CLIENT_IDeOIDC_CLIENT_SECRETe registrehttps://<seu endereço do dashboard>/api-gateway/auth/oidc/callbackcomo a URI de redirecionamento do cliente. A página de login oferece então Sign in with (Entrar com) seguido porOIDC_NAME(padrãoSSO). - Liste quem pode entrar em
OIDC_ALLOWED_EMAILS, separados por vírgula: um endereço ([email protected]), um domínio (@example.com) ou seus subdomínios (@*.example.com). Um endereço listado e verificado recebe uma conta e um livro-razão padrão na primeira vez que faz login. Sem a lista, o provedor apenas faz login em contas já vinculadas a ele.
Todos os que você deixar entram com seu disco e chave de modelo, sem limites de plano. Com um provedor, qualquer um pode entrar; liste endereços em vez de um domínio como @gmail.com.
Redefinir uma senha esquecida
Sem a SEND_GRID_API_KEY, a página de "esqueci a senha" informa ao usuário que o servidor não pode enviar e-mail. Forneça a ele um link de redefinição único a partir da API de administração em vez disso. Copie ADMIN_TOKEN da aba Environment do serviço beancount-api e chame o endereço onbex.co desse serviço, e não o do painel:
read -rs ADMIN_TOKEN; export ADMIN_TOKEN
curl -sS -X POST "https://<seu endereço da API>/api/admin/password-reset-link" \
-H "x-admin-token: $ADMIN_TOKEN" -H "Content-Type: application/json" \
-d '{"email":"[email protected]"}'Envie o resetUrl retornado para o usuário por um canal em que confia. Funciona uma vez e expira após uma hora.
A API de administração é acessível por qualquer um que consiga acessar o endereço da API, e apenas o ADMIN_TOKEN a protege. O token pode fazer login como qualquer usuário, portanto, trate-o como uma senha raiz: mantenha-o fora do histórico do shell e de chats, e rotacione-o se houver chance de vazamento.
Atualizar para uma versão mais recente
A pilha permanece na versão que você implantou até que você a atualize. Um Blueprint criado pelo botão não recebe um webhook de push, então uma atualização leva dois passos:
- Sincronize o Blueprint para aplicar mudanças em suas configurações (API bex:
POST /v1/blueprints/<id>/sync). - Implante cada serviço no novo commit, porque mudanças no código precisam de uma compilação (
POST /v1/services/<id>/deployscomcommitId).
O bex constrói um serviço por vez e a API é a última a ser construída, então um lançamento completo pode levar a maior parte de uma hora. Antes de sincronizar um Blueprint mais recente em uma pilha que contém dados, leia Atualizar uma pilha que já está rodando e faça backup primeiro.
Fazer backup e restaurar
Os livros-razão são repositórios Git no disco do Gitea. Contas, tokens de acesso pessoal e configurações vivem no Postgres gerenciado. Faça backup de cada um da sua maneira.
Livros-razão
Um clone espelho (mirror clone) é um backup completo dos arquivos e histórico de um livro-razão:
git clone --mirror https://<seu endereço da API>/git/<dono>/<ledger>.gitExecute em uma máquina onde bea cloud git setup foi executado, ou com o helper de token de Git sem bea. Para restaurar, exclua o livro-razão no painel se ainda estiver listado e crie um com o mesmo nome. O servidor se recusa a fazer push forçado para a branch principal de um livro-razão, então mescle o backup sobre o primeiro commit do novo livro-razão, usando um token com ledger.write quando não usar bea:
git clone https://<seu endereço da API>/git/<dono>/<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 HEADO banco de dados
O bex faz backup contínuo do beancount-backend-db e pode restaurá-lo como estava em um momento anterior. Ele restaura em um novo banco de dados, nunca no lugar, portanto, você copia esse banco de dados sobre o da pilha:
-
No bex, abra
beancount-backend-db, escolha Recovery (Recuperação), sele um momento de pelo menos dez minutos atrás e restaure. O bex cria um novo banco de dados com os dados até aquele momento. -
Suspend
beancount-apiebeancount-gitea, para que nada escreva enquanto você restaura. -
Copie os dados com
pg_dumpepg_restoredo PostgreSQL 16 (a imagem Dockerpostgres:16tem ambos). Use a string de conexão externa dobeancount-backend-dbpara ambos os lados, e para a cópia mude apenas o host para o da cópia. Não use os detalhes de conexão que o bex mostra para a cópia; eles nomeiam um banco de dados e um usuário que não conseguem ler os dados restaurados.read -rs DB_URL; export DB_URL # string de conexão externa do beancount-backend-db 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_restorerelata que pode não remover as extensõesvectorepg_stat_statements; esses erros são esperados. Se o certificado da cópia ainda estiver sendo emitido, adicione?sslmode=verify-fullaoCOPY_URLe salve o CA que o bex mostra para a cópia como~/.postgresql/root.crt. Se a conexão expirar, tente novamente. -
Retome
beancount-giteaebeancount-api, e então exclua a cópia.
O que sai do seu espaço de trabalho
A pilha não envia análise ou telemetria para o Beancount.io, e o script de análise do navegador está fora da compilação. Os únicos pedidos de saída que conhecemos são:
- Verificações de violação de senha: os cinco primeiros caracteres do hash SHA-1 de uma nova senha, verificados por k-anônimos, para que nem a senha nem a conta sejam revelados.
- Avatares: o navegador pede uma imagem ao Gravatar por um hash do endereço de e-mail do usuário.
- Feeds: os feeds do blog e changelog do Beancount.io, que recebem apenas uma preferência de idioma.
- Feeds de preços: solicitações ao beancount.io somente quando um livro-razão inclui uma URL de preço gerenciada.
- Suas integrações: o que quer que você conecte, como um provedor de modelo, SendGrid, S3, Plaid ou seu provedor de identidade.
A tabela de privacidade em PRFAQ006 diz quando cada solicitação é disparada. Seus serviços, disco e banco de dados funcionam na infraestrutura do bex, sob a política de privacidade e termos de serviço do bex. O bex é construído pela Stargately, Inc., a empresa por trás do Beancount.io; o serviço Beancount.io hospedado é separado da sua pilha e não retém nenhum de seus segredos.
Remover a pilha
Excluir os recursos interrompe a cobrança e apaga seus dados junto com eles. Clone todos os livros-razão primeiro.
Faça backup conforme descrito acima, então exclua os seis recursos no bex, seguidos pelo Blueprint. Para remover apenas sua própria conta e manter a pilha, exclua-a em Settings → General → Danger Zone (Configurações → Geral → Zona de Perigo), assim como no serviço hospedado; excluir a única conta reabre o cadastro.
Executar em seu próprio servidor em vez disso
O deployment Docker executa a mesma pilha em qualquer servidor que você controle. As notas de implantação do bex cobrem cada configuração neste guia em mais detalhes.
Encontrou um problema? Abra uma issue no GitHub ou pergunte no chat do Telegram do Beancount.