A background service that automatically runs the bank sync on a scheduled basis on Actual Budget.
It connects to your Actual Budget server with the official @actual-app/api, downloads your budgets, runs the bank sync, and pushes the changes back to the server — on whatever schedule you configure.
- Automatically runs bank sync on all your Actual Budget accounts on a configurable cron schedule
- Syncs multiple budgets in a single run
- Supports end-to-end encrypted budgets via per-budget encryption passwords
- Pushes updated account balances back to the server through CRDT writes
- Self-healing retries: on a failed budget sync it rebuilds the API session and clears stale local cache before retrying
- Optional per-account sync mode that skips failing accounts instead of aborting the whole budget
- Reads configuration from the environment or from files (Docker secrets) via the
_FILEconvention - Ships as a Docker image that runs as a non-root user and supports a read-only root filesystem
- Optional notifications for sync failures and new uncategorized transactions, compatible with Apprise API
- Optional heartbeat URL pings for dead-man's-switch monitors such as Healthchecks.io, Uptime Kuma, Cronitor, and Watchgoose
- Configurable logging levels for monitoring and debugging
- Uses the official Actual Budget API for reliable synchronization
| Variable | Required | Default | Description |
|---|---|---|---|
ACTUAL_SERVER_URL |
Yes | — | URL of your Actual Budget server. |
ACTUAL_SERVER_PASSWORD |
Yes | — | Password for your Actual Budget server. |
ACTUAL_BUDGET_SYNC_IDS |
Yes | — | Comma-separated list of budget sync IDs to sync (e.g. 1cf9fbf9-...,030d7094-...). |
ENCRYPTION_PASSWORDS |
No | (empty) | Comma-separated encryption passwords, positionally matched to ACTUAL_BUDGET_SYNC_IDS. See note below. |
CRON_SCHEDULE |
No | 0 1 * * * (daily at 1am) |
Cron expression for scheduling syncs. |
TIMEZONE |
No | Etc/UTC (America/New_York in the Docker image) |
IANA time zone applied to CRON_SCHEDULE (e.g. America/New_York). |
LOG_LEVEL |
No | info |
One of debug, info, warn, error. At warn/error the verbose console output from @actual-app/api is suppressed. |
RUN_ON_START |
No | false |
Run a sync immediately on startup, in addition to the schedule. See note below. |
SKIP_FAILED_ACCOUNTS |
No | false |
Sync each account individually and skip failing ones instead of aborting the budget. See note below. |
ACTUAL_DATA_DIR |
No | ./data (/data in the Docker image) |
Directory where budget data and caches are written. Point at a mounted/tmpfs path to run with a read-only root filesystem. |
NOTIFICATION_URL |
No | (unset) | HTTP(S) endpoint accepting Apprise JSON. Notifications are disabled unless set. |
NOTIFY_ON_FAILURE |
No | true |
Notify on final sync failures or warnings, including skipped accounts and balance errors. |
NOTIFY_ON_SUCCESS |
No | false |
Notify on every fully successful sync run. |
NOTIFY_ON_NEW_UNCATEGORIZED |
No | true |
Notify when a run imports new transactions that still need categories. |
NOTIFICATION_TIMEOUT_MS |
No | 10000 |
Delivery timeout in milliseconds (1–300000). Delivery failures are logged without retrying bank sync. |
HEARTBEAT_URL |
No | (unset) | HTTP(S) URL pinged after a fully successful sync run. No success ping is sent unless this is set. |
HEARTBEAT_FAILURE_URL |
No | (unset) | HTTP(S) URL pinged when a run fails or finishes partially. Skipped when unset. |
HEARTBEAT_START_URL |
No | (unset) | HTTP(S) URL pinged once at the start of a run so a monitor can measure duration. |
HEARTBEAT_METHOD |
No | GET |
GET or POST. POST sends no body. |
HEARTBEAT_TIMEOUT_MS |
No | 10000 |
Ping timeout in milliseconds (1–300000). A ping failure is logged and leaves the sync result unchanged. |
You can find your budget sync IDs in the Actual Budget app > Selected Budget > Settings > Advanced Settings > Sync ID.
Boolean variables (RUN_ON_START, SKIP_FAILED_ACCOUNTS, NOTIFY_ON_FAILURE, NOTIFY_ON_SUCCESS, NOTIFY_ON_NEW_UNCATEGORIZED) accept true/false, 1/0, yes/no, or on/off.
ENCRYPTION_PASSWORDS — Leave empty if you don't encrypt your budgets. The position of each password matches the position of the budget in ACTUAL_BUDGET_SYNC_IDS. To skip a budget (no password), leave its slot empty by placing a comma in that position, e.g. password1,,password3.
RUN_ON_START — When set to true you may get a notice email from SimpleFIN (if you use that service), as they expect only one bank sync per day.
SKIP_FAILED_ACCOUNTS — When false, all accounts sync in a single request and any one failure aborts the budget's sync. When true, each account syncs individually and a failing account is logged and skipped so the rest still sync. Note: per-account syncing can result in more requests to your bank aggregator (e.g. SimpleFIN), which may matter for rate limits.
Set NOTIFICATION_URL to an HTTP endpoint that accepts Apprise-compatible JSON:
NOTIFICATION_URL=http://apprise:8000/notify/actual-auto-sync
NOTIFY_ON_FAILURE=true
NOTIFY_ON_SUCCESS=false
NOTIFY_ON_NEW_UNCATEGORIZED=true
NOTIFICATION_TIMEOUT_MS=10000Apprise API relays each summary to the destinations you choose (Discord, Telegram, ntfy, email, and many more). No Apprise or Python installation is needed in the sync container.
-
Run Apprise API next to the sync service:
services: apprise: image: caronc/apprise:latest ports: - '127.0.0.1:8000:8000' # web UI from this host only; Apprise has no authentication by default volumes: - apprise-config:/config # keeps saved configurations across restarts actual-auto-sync: image: seriouslag/actual-auto-sync:latest environment: # ...your existing settings... - NOTIFICATION_URL=http://apprise:8000/notify/actual-auto-sync volumes: apprise-config:
-
Save a configuration named
actual-auto-syncthat lists your destinations. Either openhttp://localhost:8000/cfg/actual-auto-syncin a browser, or use the API:curl -X POST -H 'Content-Type: application/json' \ -d '{"urls": "discord://webhook_id/webhook_token"}' \ http://localhost:8000/add/actual-auto-sync
Destination URLs such as
discord://...ormailto://...belong in Apprise, whileNOTIFICATION_URLis Apprise's HTTP endpoint for that saved configuration. The configuration name is the last segment ofNOTIFICATION_URL. -
Optionally, send a test alert by starting the sync service once with
RUN_ON_START=trueandNOTIFY_ON_SUCCESS=true. If nothing arrives, check the sync service logs: an unknown configuration name is logged asNotification delivery failed.withstatus: 404.
The Apprise service must be reachable from the sync container; apprise above is its Docker Compose service name. Apprise uses the summary's type (success, warning, or failure) to pick each destination's icon or color.
By default, alerts are sent for failures and new uncategorized transactions. Set NOTIFY_ON_SUCCESS=true to also receive routine success alerts. Each run sends at most one summary after all budgets, retries, and API shutdown finish. Final failures use type: failure; skipped accounts, balance persistence errors, or transaction-query errors use type: warning. Successful runs use type: success. A recovered retry alone does not trigger a failure alert.
Alerts list the accounts needing attention with a short reason, such as Checking (re-authentication required). With SKIP_FAILED_ACCOUNTS=true, these are the skipped accounts. With SKIP_FAILED_ACCOUNTS=false, a single request syncs every account, and the failing ones are identified from the bank sync status Actual records for each account, so no extra bank requests are made.
New-transaction alerts compare bank import identities before and after each budget sync. Pending bank transactions without a bank-provided ID use their ledger identity; becoming booked does not alert again if the ledger identity is retained. Existing uncategorized transactions do not cause repeated alerts, and a retry within the same run retains the original baseline. Categorized transactions, transfers, and off-budget accounts are excluded. An imported split counts once if any split item still needs a category. Transactions imported on a run that ultimately fails to upload that budget are not reported as successfully synced new transactions.
The endpoint receives a POST with title, body, type, and format: text. Summaries include budget sync IDs, names and sync-status reasons of accounts needing attention, and transaction counts; they omit transaction amounts, payees, notes, raw bank data, and raw error messages. A count is marked unavailable when inspection is disabled or unsuccessful. Use the service logs for error details. A delivery failure or timeout is logged and never retries the bank sync. Delivery is best-effort: missed notifications are not queued for a later run.
All notification settings support the _FILE convention below. For example, use NOTIFICATION_URL_FILE to load an endpoint from a Docker secret. This first integration supports endpoints that accept POSTs without additional authentication headers; for Apprise, configure an appropriately accessible saved configuration or use a proxy that supplies authentication.
Optional dead-man's-switch pings for any monitor that accepts an HTTP request. This is separate from Apprise notifications. When the heartbeat variables are unset, the service sends no pings and sync behavior stays the same.
A token in the path, query, or userinfo is a secret. Logs include the host only, at debug when a ping succeeds and at warn when it fails.
HEARTBEAT_URL=https://hc-ping.com/your-uuid-here
HEARTBEAT_FAILURE_URL=https://hc-ping.com/your-uuid-here/fail
HEARTBEAT_START_URL=https://hc-ping.com/your-uuid-here/start
HEARTBEAT_METHOD=GET
HEARTBEAT_TIMEOUT_MS=10000Each scheduled run, including a run started by RUN_ON_START, sends at most one start ping and then one outcome ping.
HEARTBEAT_START_URL, when set, is pinged once before budgets are downloaded. Budget retries stay inside that same run and do not send another start ping.HEARTBEAT_URLis pinged when the run is fully successful. That is the same outcome Apprise labelstype: success: every budget status issuccess, and the run has no cycle-level errors.HEARTBEAT_FAILURE_URLis pinged when the run is anything else. That includes a budget that still fails after retries, an initialization failure, an API shutdown failure, and a partial run. When this variable is unset, those runs send no outcome ping.
Partial runs count as heartbeat failures. With SKIP_FAILED_ACCOUNTS=true, a skipped account leaves that budget partial (an Apprise warning). Balance persistence errors and transaction-inspection warnings do too. Those runs ping HEARTBEAT_FAILURE_URL, so the monitor records a failed check. A missed run remains the case where no outcome ping arrives at all. A retry that recovers before the run finishes is a success and pings HEARTBEAT_URL.
Each ping is a single request. A timeout, network error, or non-success HTTP status is logged at warn with the host only. The sync result stays whatever the bank sync produced, and the service does not retry the ping.
All heartbeat settings support the _FILE convention below. For example, use HEARTBEAT_URL_FILE to load a URL from a Docker secret.
HEARTBEAT_URL=https://hc-ping.com/your-uuid-here
HEARTBEAT_FAILURE_URL=https://hc-ping.com/your-uuid-here/fail
HEARTBEAT_START_URL=https://hc-ping.com/your-uuid-here/startCreate a Push monitor and use its push URL. Set the up and down URLs. Leave HEARTBEAT_START_URL unset; a Kuma push monitor has an up signal and a down signal.
HEARTBEAT_URL=https://kuma.example.com/api/push/your-token?status=up&msg=OK&ping=
HEARTBEAT_FAILURE_URL=https://kuma.example.com/api/push/your-token?status=down&msg=DOWN&ping=Include state on each URL. A Cronitor /p/ ping without state records a tick.
HEARTBEAT_URL=https://cronitor.link/p/your-api-key/your-monitor?state=complete
HEARTBEAT_FAILURE_URL=https://cronitor.link/p/your-api-key/your-monitor?state=fail
HEARTBEAT_START_URL=https://cronitor.link/p/your-api-key/your-monitor?state=runHEARTBEAT_URL=https://watchgoose.com/ping/your-check-uuid
HEARTBEAT_FAILURE_URL=https://watchgoose.com/ping/your-check-uuid/fail
HEARTBEAT_START_URL=https://watchgoose.com/ping/your-check-uuid/startYou can set any environment variable from a file by using a special append _FILE.
As an example:
-e MYVAR_FILE=/run/secrets/mysecretvariableWill set the environment variable MYVAR based on the contents of the /run/secrets/mysecretvariable file.
If both MYVAR and MYVAR_FILE are set, MYVAR_FILE takes precedence.
In your Actual Budget Server config, you must be able to log in with a password.
Set the following settings in your Actual Budget Server, then on initial login, you must set a password:
services:
...
actual_budget_server:
image: actualbudget/actual-server:latest
environment: ...
- ACTUAL_OPENID_AUTH_METHOD=openid
- ACTUAL_LOGIN_METHOD=openid
- ACTUAL_ALLOWED_LOGIN_METHODS=openid,password,header
- ACTUAL_OPENID_ENFORCE=false
...
...Images are published as multi-arch manifests, so docker pull / docker run automatically selects the right build for your host.
Two image variants are published, mirroring the upstream Actual Budget server images and the Node.js version Actual uses (24):
| Variant | Tags | Base | Platforms |
|---|---|---|---|
| Default | latest, vX.Y.Z.N, … |
Debian (node:24-bookworm-slim) |
linux/amd64, linux/arm64 |
| Alpine | latest-alpine, vX.Y.Z.N-alpine, … |
Alpine (alpine:3.24 + its nodejs package) |
linux/amd64, linux/arm64, linux/arm/v7 |
linux/amd64— x86-64 (Intel/AMD)linux/arm64— 64-bit ARM (ARM64/aarch64), e.g. Apple Silicon, an ARM-based NAS/server, or a Raspberry Pi 4/5 running a 64-bit OSlinux/arm/v7— 32-bit ARM (ARMv7/armhf), e.g. a Raspberry Pi 2/3 or a Pi running a 32-bit OS — use the-alpinetags
The official Node.js 24 images are not built for 32-bit ARM, so, like Actual, 32-bit ARM is served by the Alpine variant. If you run on 32-bit ARM, switch seriouslag/actual-auto-sync:latest to seriouslag/actual-auto-sync:latest-alpine. On 32-bit ARM the process is limited to a ~2–3 GB address space, which is ample for syncing but worth noting for very large budgets.
Published tags include:
latestfor the newest successfulmainbuildvX.Y.Z.NandX.Y.Z.Ntags whereX.Y.Zmatches@actual-app/api(Actual Budget) andNis an internal release counter (for example:26.2.0.1,26.2.0.2)<commit-sha>tags for build traceability- each of the above with an
-alpinesuffix for the Alpine variant
For a pull request, maintainers can comment:
/publish-test-image
The workflow will publish a test image with a tag like seriouslag/actual-auto-sync:pr-<pr-number>-<sha8> and reply on the PR with the full image name.
docker run -d \
-e ACTUAL_SERVER_URL="your-server-url" \
-e ACTUAL_SERVER_PASSWORD="your-password" \
-e CRON_SCHEDULE="0 1 * * *" \
-e LOG_LEVEL="info" \
-e ACTUAL_BUDGET_SYNC_IDS="1cf9fbf9-97b7-4647-8128-8afec1b1fbe2" \
-e ENCRYPTION_PASSWORDS="password1" \
-e TIMEZONE="Etc/UTC" \
-e RUN_ON_START="false" \
seriouslag/actual-auto-sync:latestservices:
...
actual-auto-sync:
image: seriouslag/actual-auto-sync:latest
environment:
- ACTUAL_SERVER_URL=your-server-url
- ACTUAL_SERVER_PASSWORD=your-password
- CRON_SCHEDULE=0 1 * * *
- LOG_LEVEL=info
- ACTUAL_BUDGET_SYNC_IDS=1cf9fbf9-97b7-4647-8128-8afec1b1fbe2
- ENCRYPTION_PASSWORDS=password1
- TIMEZONE=Etc/UTC
...services:
...
actual-auto-sync:
image: seriouslag/actual-auto-sync:latest
secrets:
- actual_budget_sync_id
- actual_server_password
- encryption_passwords
environment:
- ACTUAL_SERVER_URL=your-server-url
- ACTUAL_SERVER_PASSWORD_FILE=/run/secrets/actual_server_password
- CRON_SCHEDULE=0 1 * * *
- LOG_LEVEL=info
- ACTUAL_BUDGET_SYNC_IDS_FILE=/run/secrets/actual_budget_sync_id
- ENCRYPTION_PASSWORDS_FILE=/run/secrets/encryption_passwords
- TIMEZONE=Etc/UTC
...
secrets:
actual_budget_sync_id:
file: actual_budget_sync_id.txt
actual_server_password:
file: actual_server_password.txt
encryption_passwords:
file: encryption_passwords.txtWhere files
actual_budget_sync_id.txtactual_server_password.txtencryption_passwords.txtare plain text files next to yourdocker-compose.ymland containing your secrets
The image runs as the unprivileged node user (uid/gid 1000) by default. The only path the app needs to write is its data directory, which defaults to ACTUAL_DATA_DIR=/data in the image. Mount that as a writable volume (or tmpfs) and you can lock the rest of the container down with a read-only root filesystem:
services:
actual-auto-sync:
image: seriouslag/actual-auto-sync:latest
read_only: true
volumes:
- ./actual-auto-sync-data:/data
environment:
- ACTUAL_SERVER_URL=your-server-url
- ACTUAL_SERVER_PASSWORD=your-password
- ACTUAL_BUDGET_SYNC_IDS=1cf9fbf9-97b7-4647-8128-8afec1b1fbe2The host-mounted directory must be writable by uid/gid 1000. To match a different host user, build the image with custom ids:
docker build --build-arg APP_UID=1001 --build-arg APP_GID=1001 -t actual-auto-sync .- Node.js 24.x, the major Actual Budget uses (
engines.node: ^24; CI and the Docker images pin an exact 24.x release in the Dockerfiles and workflows) - pnpm >= 11 (the exact version is pinned by
packageManagerinpackage.json; runcorepack enableto use it)
-
Install dependencies:
# Clone the repository and `cd` into the folder pnpm install -
Create a
.envfile with your configuration:ACTUAL_SERVER_URL=your-server-url ACTUAL_SERVER_PASSWORD=your-password CRON_SCHEDULE=0 1 * * * LOG_LEVEL=info ACTUAL_BUDGET_SYNC_IDS=1cf9fbf9-97b7-4647-8128-8afec1b1fbe2 ENCRYPTION_PASSWORDS=your-encryption-password # or leave empty if you don't encrypt your data, the position of the password in the list is the position of the account in the ACTUAL_BUDGET_SYNC_IDS list; to skip an account, add a comma to the list in that position
-
Start the service:
pnpm start
pnpm start # Run locally with tsx
pnpm test # Run unit tests (Vitest, watch mode)
pnpm test:coverage # Run unit tests once with coverage
pnpm test:e2e # Run e2e tests (needs an Actual server on localhost:5006)
pnpm test:e2e:docker # Run e2e tests in Docker (spins up the server automatically)
pnpm test:watchgoose # Live Watchgoose heartbeat test (needs WATCHGOOSE_API_KEY; not part of CI)
pnpm build # Type-check / compile with tsc
pnpm lint # Lint with oxlint
pnpm format # Format with oxfmt
pnpm check # lint + format check + buildpnpm test:watchgoose creates a temporary Watchgoose check with no alert channels, drives the heartbeat client through start, a full success, and a partial run, then deletes the check. Set WATCHGOOSE_API_KEY to a read-write project key. WATCHGOOSE_API_URL is optional and defaults to https://watchgoose.com. GitHub Actions runs this every Monday at 16:17 UTC from the WATCHGOOSE_API_KEY secret and the optional WATCHGOOSE_API_URL variable. You can also run the "Watchgoose integration" workflow by hand. Pull requests and the main deploy workflow do not run it.
docker build -t actual-auto-sync .
docker run -d \
actual-auto-syncMIT
A: Double-check ACTUAL_SERVER_PASSWORD. For HTTPS connection errors, keep TLS verification enabled and fix certificate trust instead of disabling TLS checks globally.
# example for a local/self-hosted certificate chain
services:
...
actual-auto-sync:
image: seriouslag/actual-auto-sync:latest
restart: unless-stopped
environment:
- ACTUAL_SERVER_URL=https://<your-local-actual-budget-url>:<your-actual-budget-port>
- ACTUAL_SERVER_PASSWORD=<your-actual-budget-password>
- NODE_EXTRA_CA_CERTS=/path/to/ca.pem
...
...If the above does not work, verify the server certificate chain and hostname on the Actual server, then restart the container with an updated CA bundle.
