The extension talks to actual-http-api, a thin HTTP wrapper around the Actual
Budget Node API. You deploy it from the public Docker image; you don't build it.
cp .env.example .env # fill in API_KEY + ACTUAL_SERVER_PASSWORD
docker compose up -d- Actual server: http://localhost:5006
- Bridge + Swagger UI: http://localhost:5007/api-docs/
Copy the example configs somewhere private and fill in the <placeholders>:
fly.actual.example.toml: the Actual sync server (skip if you already run it)fly.http-api.example.toml: the bridge
fly apps create <your-api-app>
fly secrets set ACTUAL_SERVER_PASSWORD='<actual password>' API_KEY='<long random>' -a <your-api-app>
fly deploy -c fly.http-api.example.toml- Secrets (
API_KEY,ACTUAL_SERVER_PASSWORD) go viafly secrets set, never in the toml.API_KEYis the whole public perimeter, so make it long and random (e.g.openssl rand -hex 32). ACTUAL_SERVER_URL: the example uses the publichttps://<server>.fly.dev/, which is TLS-encrypted and needs no extra setup. Private routing is more involved:.internalrequires the server to listen on IPv6, and.flycasttrips a TLS cert-name mismatch behindforce_https.- Pin the image version (e.g.
:26.5.2, the current latest), not:latest, and match it roughly to your Actual server version so an upstream change can't silently break sync. EXPERIMENTAL_OPERATIONS_ENABLED=true: the extension reads balances and history through the bridge'srun-query(ActualQL) endpoint, which actual-http-api treats as an experimental operation. It defaults to on upstream, but the examples set it explicitly so the bridge can't be left without it; if it's off, sync fails with501.- Encrypted budgets: the encryption password is not an env var; the bridge only
accepts it as the per-request
budget-encryption-passwordheader. The extension sends it; nothing to configure here. - Verify before touching the extension: open
/api-docs/and callGET /v1/budgets/{syncId}/accountsfrom the Swagger UI.