Why Your Finance App Knows Too Much About You
Most budgeting apps work by asking you to hand over your bank login credentials or link your accounts through a third-party aggregator. The app then pulls your transactions, categorizes your spending, and presents tidy charts – all while storing your financial data on servers you have zero control over. For anyone who has thought twice about what happens to that data after a breach, a company acquisition, or a quiet change to a terms-of-service agreement, the discomfort is reasonable.
Actual Budget is an open-source, self-hosted budgeting tool built around the envelope budgeting method – the same system that made YNAB popular before YNAB moved to a subscription model and cloud dependency. With Actual Budget, your data lives on your own server, syncs across your devices, and never touches a third-party cloud unless you explicitly set one up yourself. This guide walks through the full setup, from installing the server to importing your first transactions.
What You Need Before You Start
Actual Budget runs as a Node.js application, and the cleanest way to self-host it is through Docker. You will need a machine that stays on – a home server, a Raspberry Pi 4 or newer, an old desktop, or a VPS. The server needs Docker and Docker Compose installed. If you are already running other self-hosted services like Nextcloud as a self-hosted Google Drive alternative, you likely have this environment ready.
You should also decide upfront whether you want this accessible only on your local network or reachable over the internet. Local-only is simpler and more secure. Remote access is useful if you want to log expenses from your phone while away from home, but it requires either a VPN into your home network or a reverse proxy with HTTPS – both of which add steps beyond this guide’s scope. For most people starting out, local access is the right call.
Installing Actual Budget with Docker Compose
Create a directory for your Actual Budget installation – something like /opt/actualbudget or ~/docker/actualbudget. Inside that directory, create a file named docker-compose.yml. The configuration is minimal. The official image is actualbudget/actual-server, and the container exposes port 5006 by default. You will map that to a port on your host, define a volume for persistent data storage, and set the container to restart automatically unless you stop it manually.
A working docker-compose.yml looks like this:
- image: actualbudget/actual-server:latest
- ports: “5006:5006”
- volumes: ./data:/data
- restart: unless-stopped
Run docker compose up -d from that directory. Docker will pull the image and start the container in the background. The data folder will be created automatically and is where your budget files, server configuration, and sync state are stored. Back this folder up regularly – it contains everything.
Once the container is running, open a browser and navigate to http://your-server-ip:5006. You will be greeted by the Actual Budget setup screen. Create a server password on first launch. This password gates access to the server itself – not individual budget files, which have their own passwords. Write it down somewhere secure. Losing the server password means resetting the entire server configuration.
Creating and Configuring Your Budget
After authenticating to the server, you can create a new budget or import an existing one. New budgets start with a blank slate. You will be prompted to name the budget and set a local encryption password – this encrypts the budget file at rest on the server, so even if someone gains access to your server’s filesystem, they cannot read your financial data without this passphrase.
The envelope budgeting method that Actual Budget uses requires you to assign every dollar a job before spending happens. Start by adding your accounts – checking, savings, credit cards. Then set up your budget categories. Common structures include groups like Housing, Transportation, Food, Personal, and Savings, with line items underneath each. The software does not enforce any particular category structure, so build one that matches how you actually spend money, not an idealized version of how you think you should.
Importing Transactions and Setting Up Rules
Actual Budget does not connect to your bank automatically, which is the tradeoff for keeping your data offline. You import transactions manually using CSV or QFX files exported from your bank’s website. Most banks and credit unions support at least one of these formats in their transaction download section. For the CSV import, Actual Budget has a field-mapping step where you assign which CSV column corresponds to date, payee, amount, and notes – a one-time process per institution.
Once transactions are flowing in, the payee rules system becomes one of the most useful features. Rules let you automatically rename payees, assign categories, and even set notes based on patterns in the imported data. A transaction coming in as “SQ *COFFEE SHOP 4892” can be renamed to “Local Coffee” and auto-categorized under Food every time it appears. Rules are triggered by exact match, contains, or starts-with logic, and you can set them to apply retroactively to existing transactions when you first create them.
Reconciliation is built into the workflow rather than bolted on as an afterthought. When you finish importing and categorizing a batch of transactions, you reconcile by entering your actual bank balance and letting Actual Budget flag any discrepancies. Cleared transactions are marked separately from uncleared ones, so transactions you have entered manually but not yet seen in a bank export do not throw off the reconciliation math. This matters most when you are dealing with checks or pending transactions that have not settled yet.
Keeping the Server Running and Synced Across Devices
One of the more practical advantages of Actual Budget’s architecture is that the sync system works without cloud middlemen. If you access your budget from a laptop on your home network, then later open it on a phone connected to the same network, both clients sync to the same server and changes propagate automatically. The sync is conflict-aware, handling cases where you make edits on two devices before one has had a chance to sync.
For updates, the process is simple: pull the new Docker image with docker compose pull, then bring the container back up with docker compose up -d. Your data volume persists across image updates, so nothing is lost. Setting a reminder to check for updates monthly is enough for a tool that does not face active security threats the way a public-facing web server might. The project maintains a changelog at its GitHub repository, so you can review what changed before pulling a new version.
The Honest Limitations
Actual Budget will not automatically pull your transactions. That manual CSV download and import step is either a minor inconvenience or a dealbreaker depending on how many accounts you manage. Someone tracking two accounts can do the full import in under five minutes per week. Someone managing eight accounts across multiple institutions is looking at a more meaningful time investment, and the lack of automation will feel like a genuine friction point rather than a reasonable tradeoff.
The mobile experience also deserves a candid assessment. Actual Budget’s web app runs in a mobile browser and is functional, but it was designed as a desktop-first tool. Logging a quick expense from your phone mid-day works, but navigating the full budgeting interface on a small screen is not where the app shines. There is no native mobile app in the current release, though the project’s GitHub discussions suggest this remains an area of active interest from contributors. If on-the-go logging is central to how you budget, that gap is worth factoring in before committing to the setup.
