# Hospede o Beancount.io no bex com um clique

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](/blog/2026/11/18/run-your-own-beancount-io-from-one-button).

## Implante a pilha

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

1. **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.
2. **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.
3. **Reivindique sua instância.** Abra a URL do serviço `beancount-dashboard` e cadastre-se imediatamente. Não há etapa de verificação de e-mail, e o registro fecha após a primeira conta.
4. **Crie um livro-razão.** Comece pelo modelo inicial ou carregue o livro-razão de exemplo para dar uma olhada.

:::warning
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](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) para reabrir o cadastro.
:::

![Registro em um novo deployment auto-hospedado. Ao lado do formulário, a página diz que esta cópia é executada por seu proprietário e os livros são texto simples no Git.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

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`](https://beancount.io/pt/docs/Basics/bea-cli) com `uv tool install beancount-io` ou `brew install bex-co/tap/bea`, depois aponte-o para o seu painel:

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

Ambas as variáveis usam o endereço do dashboard, porque o dashboard encaminha o tráfego da API. A [referência da CLI Beancount](https://beancount.io/pt/docs/bea-cli-reference) 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:

```zsh
claude mcp add --transport http beancount \
  https://<seu endereço do dashboard>/api-gateway/mcp
```

Faç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:

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

Depois 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.

![Menu Git Clone de um livro-razão: 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)

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

1. **Crie um token.** No painel, abra **Settings → Personal access tokens → New token**. Dê um nome para onde será executado (`laptop`, `backup-diário`), escolha `ledger.read` para clonar e puxar, e adicione `ledger.write` se fizer push. Para um script sem acompanhamento, limite a um livro-razão e defina um prazo de validade. Copie o token `bcio_` agora; ele é mostrado apenas uma vez.
2. **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).

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

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:

```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://<seu endereço da API>/git/<dono>/<ledger>.git
```

O `-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:

```zsh
printf 'protocol=https\nhost=<seu endereço da API>\n\n' | git credential reject
```

### O aplicativo móvel

Na tela de boas-vindas do aplicativo [iOS](/beancount-ios) ou [Android](/beancount-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`:

1. Defina `OIDC_ISSUER`, `OIDC_CLIENT_ID` e `OIDC_CLIENT_SECRET` e registre `https://<seu endereço do dashboard>/api-gateway/auth/oidc/callback` como a URI de redirecionamento do cliente. A página de login oferece então **Sign in with** (Entrar com) seguido por `OIDC_NAME` (padrão `SSO`).
2. Liste quem pode entrar em `OIDC_ALLOWED_EMAILS`, separados por vírgula: um endereço (`alice@example.com`), 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:

```zsh
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":"user@example.com"}'
```

Envie o `resetUrl` retornado para o usuário por um canal em que confia. Funciona uma vez e expira após uma hora.

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

1. **Sincronize o Blueprint** para aplicar mudanças em suas configurações (API bex: `POST /v1/blueprints/<id>/sync`).
2. **Implante cada serviço no novo commit**, porque mudanças no código precisam de uma compilação (`POST /v1/services/<id>/deploys` com `commitId`).

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](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running) 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:

```zsh
git clone --mirror https://<seu endereço da API>/git/<dono>/<ledger>.git
```

Execute 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`:

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

### O 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:

1. 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.
2. Suspend `beancount-api` e `beancount-gitea`, para que nada escreva enquanto você restaura.
3. Copie os dados com `pg_dump` e `pg_restore` do PostgreSQL 16 (a imagem Docker `postgres:16` tem ambos). Use a string de conexão externa do `beancount-backend-db` para 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.

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

   `pg_restore` relata que pode não remover as extensões `vector` e `pg_stat_statements`; esses erros são esperados. Se o certificado da cópia ainda estiver sendo emitido, adicione `?sslmode=verify-full` ao `COPY_URL` e salve o CA que o bex mostra para a cópia como `~/.postgresql/root.crt`. Se a conexão expirar, tente novamente.
4. Retome `beancount-gitea` e `beancount-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](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) 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](https://bex.co/privacy-policy) e [termos de serviço](https://bex.co/terms-of-service) 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

:::warning
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](https://beancount.io/pt/docs/request-to-delete-account); excluir a única conta reabre o cadastro.

## Executar em seu próprio servidor em vez disso

O [deployment Docker](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) executa a mesma pilha em qualquer servidor que você controle. As [notas de implantação do bex](https://github.com/bex-co/beancount-io/tree/main/deploy/bex) cobrem cada configuração neste guia em mais detalhes.

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