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.
Desplegar el stack
- 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.
- 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.
- Reclama tu instancia. Abre la URL del servicio
beancount-dashboardy regístrate de inmediato. No hay paso de verificación por correo electrónico, y el registro se cierra tras la primera cuenta. - Crea un libro contable. Empieza desde la plantilla inicial, o carga el libro de ejemplo para explorar.
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 para reabrir el registro.

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 con uv tool install beancount-io o brew install bex-co/tap/bea, luego apúntala a tu panel:
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 listAmbas 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 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:
claude mcp add --transport http beancount \
https://<your dashboard address>/api-gateway/mcpInicia 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:
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>.gitDespué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.

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:
- Crea un token. En el panel, abre Settings → Personal access tokens → New token. Nómbralo según dónde se ejecuta (
laptop,nightly-backup), eligeledger.readpara clonar y hacer pull, y añadeledger.writesi hace push. Para un script desatendido, limítalo a un solo libro y establece una caducidad. Copia el tokenbcio_ahora; solo se muestra una vez. - 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).

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:
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>.gitEl -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:
printf 'protocol=https\nhost=<your API address>\n\n' | git credential rejectLa app móvil
En la pantalla de bienvenida de la app de iOS o 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:
- Establece
OIDC_ISSUER,OIDC_CLIENT_IDyOIDC_CLIENT_SECRET, y registrahttps://<your dashboard address>/api-gateway/auth/oidc/callbackcomo URI de redirección del cliente. La página de inicio de sesión ofrece entonces Sign in with seguido deOIDC_NAME(por defectoSSO). - Enumera quién puede unirse en
OIDC_ALLOWED_EMAILS, separados por comas: una dirección ([email protected]), 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:
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":"[email protected]"}'Envía el resetUrl devuelto al usuario por un canal de confianza. Funciona una vez y caduca después de una hora.
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:
- Sincroniza el Blueprint para aplicar cambios a sus ajustes (API de bex:
POST /v1/blueprints/<id>/sync). - Despliega cada servicio en el nuevo commit, porque los cambios de código necesitan una compilación (
POST /v1/services/<id>/deploysconcommitId).
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 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:
git clone --mirror https://<your API address>/git/<owner>/<ledger>.gitEjecú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:
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 HEADLa 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:
-
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. -
Suspende
beancount-apiybeancount-gitea, para que nada escriba mientras restauras. -
Copia los datos de vuelta con
pg_dumpypg_restorede PostgreSQL 16 (la imagen Dockerpostgres:16tiene ambos). Usa la cadena de conexión externa debeancount-backend-dbpara 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.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.dumppg_restoreinforma que puede que no elimine las extensionesvectorypg_stat_statements; esos errores son esperados. Si el certificado de la copia aún se está emitiendo, añade?sslmode=verify-fullaCOPY_URLy guarda el CA que bex muestra para la copia como~/.postgresql/root.crt. Si la conexión se agota, reintenta. -
Reanuda
beancount-giteaybeancount-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 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 y los términos de servicio 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
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; eliminar la única cuenta reabre el registro.
Ejecutarlo en tu propio servidor en su lugar
El despliegue con Docker ejecuta el mismo stack en cualquier servidor que controles. Las notas de despliegue de bex cubren cada ajuste de esta guía con más profundidad.
¿Encontraste un obstáculo? Abre un issue en GitHub o pregunta en el chat de Telegram de Beancount.