Skip to content

About

A background service that automatically runs the bank sync on a scheduled basis on Actual Budget.

Topics

Resources

Stars

95 stars

Watchers

3 watching

Forks

Latest commit

 

History

187 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@seriouslag/actual-auto-sync

Actual Auto Sync logo

Docker Image Version Code Coverage

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.

Contents

Features

  • 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 _FILE convention
  • 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

Configuration

Environment variables

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.

Notifications

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=10000

Setting up Apprise

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

  1. 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:
  2. Save a configuration named actual-auto-sync that lists your destinations. Either open http://localhost:8000/cfg/actual-auto-sync in 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://... or mailto://... belong in Apprise, while NOTIFICATION_URL is Apprise's HTTP endpoint for that saved configuration. The configuration name is the last segment of NOTIFICATION_URL.

  3. Optionally, send a test alert by starting the sync service once with RUN_ON_START=true and NOTIFY_ON_SUCCESS=true. If nothing arrives, check the sync service logs: an unknown configuration name is logged as Notification delivery failed. with status: 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.

What gets sent

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.

Heartbeat monitoring

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=10000

When each URL is pinged

Each 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_URL is pinged when the run is fully successful. That is the same outcome Apprise labels type: success: every budget status is success, and the run has no cycle-level errors.
  • HEARTBEAT_FAILURE_URL is 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.

Healthchecks.io

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

Uptime Kuma

Create 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=

Cronitor

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=run

Watchgoose

HEARTBEAT_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/start

Environment variables from files (Docker secrets)

You can set any environment variable from a file by using a special append _FILE.

As an example:

-e MYVAR_FILE=/run/secrets/mysecretvariable

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

If using with OIDC auth provider in Actual Budget Server

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

Running with Docker (pull from Docker Hub)

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 OS
  • linux/arm/v7 — 32-bit ARM (ARMv7/armhf), e.g. a Raspberry Pi 2/3 or a Pi running a 32-bit OS — use the -alpine tags

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:

  • latest for the newest successful main build
  • vX.Y.Z.N and X.Y.Z.N tags where X.Y.Z matches @actual-app/api (Actual Budget) and N is 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 -alpine suffix for the Alpine variant

Publish a PR test image (maintainers)

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.

direct docker run

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

Running with docker compose

services:
...
  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
  ...

Running with docker compose with docker secrets

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

Where files

  • actual_budget_sync_id.txt
  • actual_server_password.txt
  • encryption_passwords.txt are plain text files next to your docker-compose.yml and containing your secrets

Running as non-root with a read-only filesystem

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-8afec1b1fbe2

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

Development

Prerequisites

  • 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 packageManager in package.json; run corepack enable to use it)

Setup local (non-docker)

  1. Install dependencies:

    # Clone the repository and `cd` into the folder
    pnpm install
  2. Create a .env file 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
  3. Start the service:

    pnpm start

Scripts

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 + build

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

Running with Docker (build locally)

docker build -t actual-auto-sync .
docker run -d \
  actual-auto-sync

License

MIT

FAQ

Q: I am getting connection errors.

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.

About

A background service that automatically runs the bank sync on a scheduled basis on Actual Budget.

Topics

Resources

Stars

95 stars

Watchers

3 watching

Forks

Sponsor this project

Used by

Contributors

Languages