xrous/actual-bench repository overview

⁠Actual Bench

The advanced admin, budgeting, diagnostics, sync, reconciliation, and ActualQL workbench for Actual Budget.

Actual Bench is a companion application for Actual Budget⁠ designed for the work that becomes cumbersome in the standard Actual UI: bulk data management, full-year budgeting, advanced rule maintenance, diagnostics, cross-budget workflows, reconciliation, automation, and ad-hoc analysis.

It is not a replacement for Actual Budget's everyday transaction experience. Think of it as the workbench you open when you need to inspect, repair, organize, audit, reconcile, sync, or reshape your budget data.

⁠Key Features

• 12-Month Budget Workspace — Edit Envelope and Tracking budgets across a full year with spreadsheet-style navigation, multi-cell selection, copy/paste, fill actions, bulk calculations, notes, staged transfers, and undo/redo.
• Advanced Data Management — Manage accounts, payees, categories, schedules, tags, and rules with inline editing, filtering, bulk actions, and CSV import/export.
• Rules Management & Diagnostics — Build complex rules, merge and duplicate them, resolve entity names, and detect broken references, duplicates, near-duplicates, broad rules, and other potential issues.
• Safe Staged Editing — Changes are staged locally where supported until you explicitly save, allowing you to review and undo changes before they reach Actual.
• Budget File Health & Data Browser — Inspect exported Actual Budget SQLite files locally in the browser, run integrity and relationship checks, explore tables, views, indexes, triggers, and schema, and export findings.
• Budget File Sync — Create preview-first flows for transactions, payees, and categories between Actual budgets with duplicate protection, review queues, run history, and safe automation.
• Multi-Currency Sync & FX Rates — Convert transactions between budgets using different currencies, automatically retrieve historical exchange rates, override rates when needed, and lock rates used for completed syncs.
• Automations — Schedule supported Actual Bench jobs with run history, failure handling, review queues, pause/resume controls, and browser or unattended server execution where supported.
• Bank Sync — Trigger Actual's connected-bank sync for SimpleFIN / GoCardless accounts directly from Actual Bench.
• Bank Statement Reconciliation — Import CSV/TSV, OFX/QFX, or QIF statements, match them against Actual transactions, review differences, correct issues, and safely apply the final reconciliation.
• ActualQL Workspace — Run, format, explain, save, replay, and export ActualQL queries with table, JSON, scalar, and tree result views.
• Multi-Budget Support — Save and switch between multiple Actual Budget connections while keeping staged data, workflow state, and query data isolated per connection.

⁠Connection Modes

Actual Bench supports two ways of connecting to Actual Budget.

⁠Direct Actual Server

The recommended architecture.

Connect directly from the browser to your Actual Budget server using Actual's browser API transport.

⁠HTTP API Server

Existing actual-http-api⁠ deployments remain fully supported for integrations and workflows that use the HTTP API bridge.

⁠Docker

Run the latest stable release:

docker run -d \
  --name actual-bench \
  --restart unless-stopped \
  -p 3000:3000 \
  -v actual-bench-data:/data \
  xrous/actual-bench:latest

Then open:

http://localhost:3000

⁠Edge Builds

The latest unreleased build from main is also available for testing:

docker run -d \
  --name actual-bench-edge \
  --restart unless-stopped \
  -p 3000:3000 \
  -v actual-bench-edge-data:/data \
  xrous/actual-bench:edge

The edge image may contain unfinished or unstable changes.

Use latest for normal deployments.

⁠Docker Compose

Save the following as docker-compose.yml:

services:
  actual-bench:
    image: xrous/actual-bench:latest
    container_name: actual-bench

    ports:
      - "3000:3000"

    environment:
      ACTUAL_BENCH_DB_PATH: /data/actual-bench.sqlite

      # --- Optional settings ---

      # Disable Direct Actual Server mode and offer only
      # HTTP API Server / actual-http-api connections.
      # DIRECT_BROWSER_API: "0"

      # Logging level: debug | info | warn | error
      # LOG_LEVEL: info

      # Enables encrypted server-side credential storage
      # for supported unattended HTTP API workflows.
      #
      # Use a strong, persistent secret and do not change
      # it after credentials have been enrolled.
      # SYNC_VAULT_KEY: "<strong-secret>"

      # Optional secret protecting the external
      # automation/scheduler trigger.
      # SYNC_SCHEDULER_SECRET: "<strong-secret>"

    volumes:
      - actual-bench-data:/data

    restart: unless-stopped

volumes:
  actual-bench-data:

Start Actual Bench with:

docker compose up -d

Then open:

http://localhost:3000

⁠Persistent Data

Actual Bench stores its own application and workflow metadata in a server-side SQLite database.

The default location is:

/data/actual-bench.sqlite

The Docker volume:

actual-bench-data:/data

should be persisted so Actual Bench configuration and app-owned data survive container recreation.

This may include data such as:

• saved workflow configuration
• automation definitions and run history
• Budget File Sync metadata and mappings
• review state
• FX rate data
• other Actual Bench application metadata

This database is not a replica of your Actual Budget database.

Your Actual Budget files and financial records remain managed by Actual Budget.

⁠Environment Variables

All additional configuration variables are optional.

⁠ACTUAL_BENCH_DB_PATH

Location of Actual Bench's server-side metadata SQLite database.

Default:

/data/actual-bench.sqlite

⁠DIRECT_BROWSER_API

Controls availability of Direct Actual Server mode.

Set:

DIRECT_BROWSER_API=0

to disable Direct mode and offer only HTTP API Server connections.

⁠LOG_LEVEL

Controls server logging verbosity.

Supported values:

debug
info
warn
error

⁠SYNC_VAULT_KEY

Enables Actual Bench's encrypted server-side credential vault.

This is required for supported unattended workflows that need Actual Bench to access an HTTP API connection while the browser is closed.

Use a strong, persistent secret.

Changing the key after credentials have been enrolled can make previously stored credentials inaccessible.

⁠SYNC_SCHEDULER_SECRET

Optional secret used to protect the external scheduler trigger when that integration is enabled.

⁠Security

Actual Bench is designed around keeping access to your Actual Budget environment under your control.

For Direct Actual Server connections, credentials remain client-side.

Server-side credentials are only stored when you explicitly enable functionality that requires unattended HTTP API execution and configure Actual Bench's encrypted credential vault.

Actual Bench's metadata database stores application-owned workflow information rather than maintaining a copy of your Actual Budget financial database.

⁠More Information

GitHub

https://github.com/x-rous/actual-bench⁠

Documentation

https://x-rous.github.io/actual-bench/⁠

Live Demo

https://actual-bench-demo.vercel.app⁠

The live demo contains a shared sandbox budget and requires no Actual Budget server.