# Project pack: Actual Budget @ 27290a8

Facts about **Actual Budget** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> Actual is a budgeting app built around envelope budgeting: you decide in advance what each part of your money is for, then track spending against it. It imports bank files (and can connect to banks in many countries), syncs between your devices, and keeps your financial data on your own device or server instead of a company's cloud.

## Setup path (checked 2026-11-03)
- **Start here, no Docker:** Install the project's own desktop app or installer. No Docker.
- Offer Docker only if the person asks or this path fails. The commands further down may use Docker; they are not the starting point.
- Verdict source: https://raw.githubusercontent.com/actualbudget/actual/HEAD/README.md
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/actualbudget/actual
- Pinned commit: `27290a8990ef8c24c71c581f4da08d6df020a009`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/actualbudget/actual/archive/27290a8990ef8c24c71c581f4da08d6df020a009.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://actualbudget.org/docs
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/actualbudget/actual bespoke-actual-budget
  cd bespoke-actual-budget
  git checkout --detach 27290a8990ef8c24c71c581f4da08d6df020a009
  # Prepare development requirements and local configuration first.
  # Setup notes: browser dev server; yarn start:server-dev to include the sync server
  yarn install && yarn start
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  docker run -d --name actual -p 5006:5006 -v actual-data:/data actualbudget/actual-server:latest # then open http://localhost:5006. Hosted options: PikaPods (simpler, about US$2/month) or Fly.io (usage-based pricing).
  ```
- Tools these commands use: Docker, or a desktop download; Node 22 + Yarn 4 for development
- Develop: `yarn install && yarn start   # browser dev server; yarn start:server-dev to include the sync server`
- Test: `yarn test`
- Check/lint: `yarn typecheck && yarn lint:fix`
- Stack: typescript (React, Vite, Node.js, Electron, Yarn 4 workspaces). Difficulty for a non-developer with an AI: **moderate**. The core is a large TypeScript monorepo, but most personal adaptations use settings, custom themes, rules, or small scripts with the official @actual-app/api package. These need no fork.
- The project's own AI instructions, in the repository: `AGENTS.md`, `CLAUDE.md`, `PRODUCT.md`, `DESIGN.md`, `CODE_REVIEW_GUIDELINES.md`.
Personal data: **yes**. Stored in: Budget files stored locally in the browser or desktop app; the sync server keeps an encrypted-capable copy in /data. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/actual-budget/27290a8/r4/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/actual-budget/27290a8/r4/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/actual-budget/27290a8/r4/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/actual-budget/27290a8/r4/SKILL.md)