# Actual Budget

Local-first envelope budgeting with an official Node API package and CLI.

Actual is a free, MIT-licensed budgeting app with a sync server you can self-host. The Builder publishes @actual-app/api, which opens a budget file (local or against your server) and exposes accounts, transactions, budgets, categories, payees, rules, schedules, bank sync and an ActualQL query engine. Personal finance, at the edge of this vertical.

Alternative to: YNAB, Monarch Money, Mint

- Capabilities: adaptable, operable
- Vertical: invoicing-finance
- Shape: product
- Form factor: web-app
- Execution model: deterministic
- Provenance: human-written (recorded, never ranked)
- Repo: https://github.com/actualbudget/actual (MIT), 28532 stars, last commit 2026-09-02
- Last activity: 2026-09-02
- Page: apps/actualbudget--actual.html
- JSON: apps/actualbudget--actual.json

## Use it when

- I want a budget my agent can post transactions into and read balances from, with the file on my own machine
- I am moving off YNAB and want an app I can script

## Gotchas

- Personal budgeting; no invoicing, clients or tax reporting
- The API opens the budget file directly and should not run against the same file the desktop app has open in some setups; read the API docs on sync
- A finished product: the Customization surface is deployment only

## Editions

- Free: Free, open source
  - source: https://github.com/actualbudget/actual
  - container: https://actualbudget.org/docs/install/docker
  - binary: https://actualbudget.org/download/
  - installable: npm install @actual-app/api
- PikaPods managed hosting (third party): $2 per month, closed source
  - hosted: https://www.pikapods.com/pods?run=actual

## Adaptable: make it yours

Effort: config-only (14 things to edit)

The sync server reads config.json or ACTUAL_* env vars for port, data directories, login method (password, header or OpenID) and upload limits. Budget behavior is data inside the budget file; there is nothing else to edit unless you fork.

- Env vars: ACTUAL_PORT, ACTUAL_HOSTNAME, ACTUAL_DATA_DIR, ACTUAL_CONFIG_PATH, ACTUAL_SERVER_FILES, ACTUAL_USER_FILES, ACTUAL_LOGIN_METHOD, ACTUAL_ALLOWED_LOGIN_METHODS, ACTUAL_HTTPS_KEY, ACTUAL_HTTPS_CERT, ACTUAL_UPLOAD_FILE_SIZE_LIMIT_MB, ACTUAL_TRUSTED_PROXIES, ACTUAL_TRUSTED_AUTH_PROXIES
- Config files: config.json
- Prompt files: none
- Accounts you'll need: GoCardless or SimpleFIN account for bank sync (optional)

## Operable: what an agent can drive

Operability: official. Interface: sdk at https://actualbudget.org/docs/api/ (published by the builder, local).

### Reach (partial coverage)

- Envelope budgeting by month: reachable. API methods getBudgetMonths, setBudgetAmount, setBudgetCarryover
- Accounts and balances: reachable. getAccounts, createAccount, closeAccount, getAccountBalance
- Add, import and edit transactions: reachable. addTransactions, importTransactions, getTransactions, updateTransaction
- Categories, groups, payees and tags: reachable. getCategories, createCategoryGroup, mergePayees, getTags
- Rules for automatic categorization: reachable. getRules, createRule, updateRule
- Scheduled transactions: reachable. getSchedules, createSchedule, updateSchedule
- Bank sync (GoCardless, SimpleFIN): reachable. runBankSync; the bank link itself is set up once in the UI
- Import from YNAB and other apps: reachable. runImport, importBudget, exportBudget
- Ad-hoc queries over your data: reachable. runQuery with ActualQL
- Custom reports and dashboards: not reachable. reports are built in the UI; the API returns data through runQuery but does not create report widgets

## Code stack

- Languages: TypeScript, JavaScript
- Frameworks: React, Electron, Express
- Package manager: yarn
- Database: SQLite
- Hosting target: Docker, Fly.io, PikaPods, desktop installers

## Skills

contributor: Repo carries contributor-facing development skills (commits, PR review, VRTs, docs, release notes), not skills for end users of the budgeting app. [contributor tooling, not adopter-facing]
- Paths: .claude/skills/*/SKILL.md, .agents/skills/

## Evidence and confidence

- formFactor: web client plus sync server; Electron desktop build in the same repo (confidence 0.95)
- executionModel: no model at runtime (confidence 0.95)
- operability: @actual-app/api and packages/cli shipped in the repo; docs at actualbudget.org/docs/api/reference (confidence 0.95)
- effort: actualbudget.org/docs/config lists config.json and ACTUAL_* variables (confidence 0.9)
- editions: README: 100% free and open source; PikaPods and Fly listed as paid hosting (confidence 0.9)
- active: GitHub pushedAt 2026-09-02
- reach:  (confidence 0.9)

## Open questions

- Whether the in-repo packages/cli is published and documented for end users, or internal

## Sources

- https://github.com/actualbudget/actual (sourcing:invoicing-finance:github)
- https://actualbudget.org/docs/api/reference (analysis:invoicing-finance)
- https://actualbudget.org/docs/config/ (analysis:invoicing-finance)