# Autoaloja Beancount.io en bex con un clic

Un clic despliega todo el stack de Beancount.io, incluidos el panel web, la API y el servidor MCP, el servicio de libros contables y tus libros respaldados por Git, en un espacio de trabajo de bex que es tuyo. Esta guía va desde el botón hasta un libro contable funcional. Luego cubre cómo conectar tus herramientas, añadir cuentas, actualizar, hacer copias de seguridad y eliminar el stack.

El stack tiene licencia MIT, no aplica límites de plan y cuesta unos \$33 al mes en alojamiento, facturados a tu espacio de trabajo. Para el anuncio, lee [Ejecuta tu propio Beancount.io con un clic](/blog/2026/11/18/run-your-own-beancount-io-from-one-button).

## Desplegar el stack

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

1. **Lánzalo.** Pulsa **Deploy to bex.co**, elige el espacio de trabajo que debe ser dueño del stack, revisa el plan y aplica. No se crea nada hasta que apruebes la vista previa, y no hay nada que rellenar: cada secreto se genera dentro de tu espacio de trabajo.
2. **Espera a la primera compilación.** Tardó 27–30 minutos en nuestras ejecuciones, y más cuando la cola de compilación de bex está ocupada. Un servicio cuyo despliegue está marcado como fallido no se reintenta; vuelve a desplegar ese servicio desde el panel de bex.
3. **Reclama tu instancia.** Abre la URL del servicio `beancount-dashboard` y regístrate de inmediato. No hay paso de verificación por correo electrónico, y el registro se cierra tras la primera cuenta.
4. **Crea un libro contable.** Empieza desde la plantilla inicial, o carga el libro de ejemplo para explorar.

:::warning
Hasta que exista la primera cuenta, cualquiera que encuentre la dirección del panel puede crearla. Si alguien se registra antes que tú, [elimina esa cuenta con el token de administrador del stack](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 el registro.
:::

![Registro en un nuevo despliegue autoalojado. Junto al formulario, la página dice que esta copia la ejecuta su dueño y que los libros son texto plano en Git.](/img/blog/run-your-own-beancount-io-from-one-button/sign-up.webp)

Cada cuenta en un stack autoalojado obtiene el nivel más alto: los libros contables, las directivas, los colaboradores y el uso de IA son ilimitados.

## Qué se ejecuta y cuánto cuesta

El Blueprint crea seis recursos en tu espacio de trabajo (precios de la vista previa del plan de bex del 2026-11-18):

| Recurso de bex | Qué hace | Coste mensual (USD) |
| --- | --- | --- |
| `beancount-dashboard` | La app web, y la única dirección pública que usas | 4.90 |
| `beancount-api` | GraphQL, REST, el servidor MCP y el proxy de Git | 4.90 |
| `beancount-ledger` | Valida y consulta tus libros (privado, sin dirección pública) | 4.90 |
| `beancount-gitea` | Almacena cada libro como un repositorio Git en un disco de 10 GB (privado) | 6.65 |
| `beancount-backend-db` | Postgres para cuentas, tokens y ajustes | 4.41 |
| `beancount-cache` | Key Value para sesiones de inicio de sesión y cachés | 7.21 |
| **Total** | | **32.97** |

Un proveedor de modelos, servicio de correo o bucket de S3 que conectes se te factura por separado.

## Activar funciones opcionales

El stack arranca sin ninguna integración. Una función que necesita una indica qué ajuste falta. Para añadir una, abre el servicio `beancount-api` en bex, añade las variables en su pestaña **Environment** y vuelve a desplegar el servicio. Una variable que añadas allí se conserva cuando más tarde sincronices el Blueprint.

| Variables | Qué activan |
| --- | --- |
| `ANTHROPIC_API_KEY` u `OPENAI_API_KEY` | Escaneo de recibos, categorización y el asistente. `bea ask` necesita `OPENAI_API_KEY`. |
| `TEMP_ASSETS_AWS_S3_*` y `PERM_ASSETS_AWS_S3_*` (`BUCKET`, `ACCESS_KEY_ID`, `SECRET_ACCESS_KEY`) | Subidas de recibos y adjuntos |
| `SEND_GRID_API_KEY` | Correo, como enlaces de restablecimiento de contraseña |
| `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` | Inicio de sesión a través de tu propio proveedor de identidad, y más cuentas (ver **Añadir más cuentas**) |

## Conectar tus herramientas

Usa la dirección del panel en todas partes excepto para Git, que usa la dirección de la API.

### La CLI de bea

Instala o actualiza [`bea`](https://beancount.io/es/docs/Basics/bea-cli) con `uv tool install beancount-io` o `brew install bex-co/tap/bea`, luego apúntala a tu panel:

```zsh
export BEA_API_URL=https://<your dashboard address>
export BEA_DASHBOARD_URL=https://<your dashboard address>
bea cloud login            # inicia sesión a través de tu navegador
bea cloud ledger list
```

Ambas variables toman la dirección del panel, porque el panel reenvía el tráfico de la API. La [referencia de la CLI de Beancount](https://beancount.io/es/docs/bea-cli-reference) enumera todos los demás comandos de `bea cloud`.

### Agentes de programación a través de MCP

Añade el servidor MCP del despliegue a Claude Code o a cualquier cliente MCP:

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

Inicia sesión con `/mcp` en Claude Code. La página de consentimiento la sirve tu propia instancia; elige el libro contable que el cliente puede usar y aprueba. Para un cliente que envíe una cabecera en su lugar, crea un token de acceso personal (más abajo) y envíalo como `Authorization: Bearer <token>`.

### Git sobre HTTPS

Cada libro contable es un repositorio Git en `https://<your API address>/git/<owner>/<ledger>.git`. Copia la dirección exacta desde el menú **Git Clone** del libro. bex no enruta SSH, así que Git funciona sobre HTTPS. En una máquina con `bea`, deja que inicie sesión en Git:

```zsh
bea cloud login            # una vez, si aún no lo has hecho
bea cloud git setup        # ahora Git inicia sesión con tu sesión de bea
git clone https://<your API address>/git/<owner>/<ledger>.git
```

Después de eso, `git clone`, `git pull` y `git push` a ese host no piden nada, y `bea cloud logout` también elimina el inicio de sesión de Git. `bea cloud ledger clone` clona por SSH, así que en este stack imprime los comandos anteriores en su lugar.

![El menú Git Clone de un libro: la dirección HTTPS de la API, con un token de acceso personal como contraseña.](/img/blog/run-your-own-beancount-io-from-one-button/git-clone-menu.webp)

### Git sin bea

En un ejecutor de CI o una máquina sin `bea`, inicia sesión en Git con un token de acceso personal:

1. **Crea un token.** En el panel, abre **Settings → Personal access tokens → New token**. Nómbralo según dónde se ejecuta (`laptop`, `nightly-backup`), elige `ledger.read` para clonar y hacer pull, y añade `ledger.write` si hace push. Para un script desatendido, limítalo a un solo libro y establece una caducidad. Copia el token `bcio_` ahora; solo se muestra una vez.
2. **Clona.** Git pide un nombre de usuario y una contraseña: introduce cualquier nombre de usuario no vacío y pega el token como contraseña. El Keychain de macOS y Git Credential Manager en Windows lo guardan para la próxima vez. En Linux, activa primero un asistente de credenciales, por ejemplo `git config --global credential.helper 'cache --timeout=86400'` (en memoria durante un día).

![Settings, Personal access tokens: un token con ledger.read y ledger.write, su prefijo, y cuándo se creó y se usó por última vez.](/img/blog/run-your-own-beancount-io-from-one-button/access-tokens.webp)

En un script, mantén el token fuera de la URL remota, donde Git lo guardaría en `.git/config`, y fuera del historial del shell. Pásaselo a Git mediante un asistente de credenciales de un solo uso:

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

El `-c credential.helper=` vacío impide que un asistente almacenado guarde el token. Pasa ambas opciones `-c` a cada `git fetch` o `git push` posterior en el script.

Si Git sigue ofreciendo una contraseña antigua o un token revocado, bórralo:

```zsh
printf 'protocol=https\nhost=<your API address>\n\n' | git credential reject
```

### La app móvil

En la pantalla de bienvenida de la app de [iOS](/beancount-ios) o [Android](/beancount-android), abre los ajustes, establece la URL del servidor como la dirección de tu panel e inicia sesión.

## Traer tus libros existentes

Crea un libro contable en el panel, clónalo, fusiona tus archivos o tu historial de Git en él y haz push. El stack abre `main.bean` como el punto de entrada del libro, así que nombra tu archivo raíz `main.bean` o usa `main.bean` para `include` tus archivos existentes.

## Añadir más cuentas

El registro permanece cerrado tras la primera cuenta. Más personas se unen a través de un proveedor de OpenID Connect que conectes, que también gestiona su inicio de sesión con dos factores. En la pestaña **Environment** del servicio `beancount-api`:

1. Establece `OIDC_ISSUER`, `OIDC_CLIENT_ID` y `OIDC_CLIENT_SECRET`, y registra `https://<your dashboard address>/api-gateway/auth/oidc/callback` como URI de redirección del cliente. La página de inicio de sesión ofrece entonces **Sign in with** seguido de `OIDC_NAME` (por defecto `SSO`).
2. Enumera quién puede unirse en `OIDC_ALLOWED_EMAILS`, separados por comas: una dirección (`alice@example.com`), un dominio (`@example.com`), o sus subdominios (`@*.example.com`). Una dirección listada y verificada obtiene una cuenta y un libro contable predeterminado la primera vez que inicia sesión. Sin la lista, el proveedor solo inicia sesión en cuentas ya vinculadas a él.

Todos a quienes dejes entrar comparten tu disco y tu clave de modelo, sin límites de plan. Con un proveedor al que cualquiera puede unirse, enumera direcciones en lugar de un dominio como `@gmail.com`.

## Restablecer una contraseña olvidada

Sin `SEND_GRID_API_KEY`, la página de contraseña olvidada indica al usuario que el servidor no puede enviar correo. Emíteles un enlace de restablecimiento de un solo uso desde la API de administración. Copia `ADMIN_TOKEN` de la pestaña **Environment** del servicio `beancount-api`, y llama a la dirección `onbex.co` propia de ese servicio, no a la del panel:

```zsh
read -rs ADMIN_TOKEN; export ADMIN_TOKEN
curl -sS -X POST "https://<your API address>/api/admin/password-reset-link" \
  -H "x-admin-token: $ADMIN_TOKEN" -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'
```

Envía el `resetUrl` devuelto al usuario por un canal de confianza. Funciona una vez y caduca después de una hora.

:::warning
La API de administración es accesible para cualquiera que pueda alcanzar la dirección de la API, y solo `ADMIN_TOKEN` la protege. El token puede iniciar sesión como cualquier usuario, así que trátalo como una contraseña de root: mantenlo fuera del historial del shell y del chat, y rótalo si puede haberse filtrado.
:::

## Actualizar a una versión más reciente

El stack permanece en la versión que desplegaste hasta que lo actualices. Un Blueprint creado desde el botón no tiene webhook de push, así que una actualización requiere dos pasos:

1. **Sincroniza el Blueprint** para aplicar cambios a sus ajustes (API de bex: `POST /v1/blueprints/<id>/sync`).
2. **Despliega cada servicio en el nuevo commit**, porque los cambios de código necesitan una compilación (`POST /v1/services/<id>/deploys` con `commitId`).

bex compila un servicio a la vez y la API compila al final, así que un despliegue completo puede tardar casi una hora. Antes de sincronizar un Blueprint más reciente en un stack que contiene datos, lee [Actualizar un stack que ya está en ejecución](https://github.com/bex-co/beancount-io/tree/main/deploy/bex#upgrading-a-stack-that-is-already-running) y haz una copia de seguridad primero.

## Copia de seguridad y restauración

Los libros contables son repositorios Git en el disco de Gitea. Las cuentas, los tokens de acceso personal y los ajustes viven en el Postgres gestionado. Haz una copia de seguridad de cada uno a su manera.

### Libros contables

Un clon espejo es una copia de seguridad completa de los archivos y el historial de un libro:

```zsh
git clone --mirror https://<your API address>/git/<owner>/<ledger>.git
```

Ejecútalo en una máquina donde se haya ejecutado `bea cloud git setup`, o con el asistente de tokens de **Git sin bea**. Para restaurar, elimina el libro contable en el panel si todavía aparece en la lista y crea uno con el mismo nombre. El servidor rechaza un push forzado a la rama principal de un libro, así que fusiona la copia de seguridad sobre el primer commit del nuevo libro, usando un token con `ledger.write` cuando no uses `bea`:

```zsh
git clone https://<your API address>/git/<owner>/<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
```

### La base de datos

bex hace copias de seguridad de `beancount-backend-db` de forma continua y puede restaurarla tal como estaba en un momento anterior. Restaura en una nueva base de datos, nunca en su lugar, así que copias esa base de datos de vuelta sobre la propia del stack:

1. En bex, abre `beancount-backend-db`, elige **Recovery**, selecciona un momento de al menos hace diez minutos y restaura. bex crea una nueva base de datos con los datos tal como estaban en ese momento.
2. Suspende `beancount-api` y `beancount-gitea`, para que nada escriba mientras restauras.
3. Copia los datos de vuelta con `pg_dump` y `pg_restore` de PostgreSQL 16 (la imagen Docker `postgres:16` tiene ambos). Usa la cadena de conexión externa de `beancount-backend-db` para ambos extremos, y para la copia cambia solo el host por el de la copia. No uses los detalles de conexión que bex muestra para la copia; nombran una base de datos y un usuario que no pueden leer los datos restaurados.

   ```zsh
   read -rs DB_URL; export DB_URL   # cadena de conexión externa de 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` informa que puede que no elimine las extensiones `vector` y `pg_stat_statements`; esos errores son esperados. Si el certificado de la copia aún se está emitiendo, añade `?sslmode=verify-full` a `COPY_URL` y guarda el CA que bex muestra para la copia como `~/.postgresql/root.crt`. Si la conexión se agota, reintenta.
4. Reanuda `beancount-gitea` y `beancount-api`, luego elimina la copia.

## Qué sale de tu espacio de trabajo

El stack no envía analíticas ni telemetría a Beancount.io, y el script de analíticas del navegador queda fuera de la compilación. Las únicas solicitudes salientes que conocemos son:

- **Comprobaciones de filtración de contraseñas:** los cinco primeros caracteres del hash SHA-1 de una nueva contraseña, comprobados por k-anonimato, de modo que no se revela ni la contraseña ni la cuenta.
- **Avatares:** el navegador pide a Gravatar una imagen mediante un hash de la dirección de correo del usuario.
- **Feeds:** los feeds del blog y el changelog de Beancount.io, que solo reciben una preferencia de idioma.
- **Feeds de precios:** solicitudes a beancount.io solo cuando un libro contable incluye una URL de precio gestionada.
- **Tus integraciones:** lo que conectes, como un proveedor de modelos, SendGrid, S3, Plaid o tu proveedor de identidad.

La [tabla de privacidad en PRFAQ006](https://github.com/bex-co/beancount-io/blob/main/docs/prfaqs/PRFAQ006-self-host-on-bex.md#12-is-my-data-private) indica cuándo se activa cada solicitud. Tus servicios, disco y base de datos se ejecutan en la infraestructura de bex, bajo la [política de privacidad](https://bex.co/privacy-policy) y los [términos de servicio](https://bex.co/terms-of-service) de bex. bex está construido por Stargately, Inc., la empresa detrás de Beancount.io; el servicio alojado de Beancount.io es independiente de tu stack y no guarda ninguno de sus secretos.

## Eliminar el stack

:::warning
Eliminar los recursos detiene la factura y elimina tus datos con ellos. Clona cada libro contable primero.
:::

Haz una copia de seguridad como se describe arriba, luego elimina los seis recursos en bex, seguidos del Blueprint. Para eliminar solo tu propia cuenta y conservar el stack, elimínala en **Settings → General → Danger Zone**, como en el [servicio alojado](https://beancount.io/es/docs/request-to-delete-account); eliminar la única cuenta reabre el registro.

## Ejecutarlo en tu propio servidor en su lugar

El [despliegue con Docker](https://github.com/bex-co/beancount-io/tree/main/deploy/docker) ejecuta el mismo stack en cualquier servidor que controles. Las [notas de despliegue de bex](https://github.com/bex-co/beancount-io/tree/main/deploy/bex) cubren cada ajuste de esta guía con más profundidad.

¿Encontraste un obstáculo? Abre un [issue en GitHub](https://github.com/bex-co/beancount-io/issues) o pregunta en el [chat de Telegram de Beancount](https://t.me/beancount).
