When you self-host Actual Budget on a managed VPS, your budgets and their sync stay on a machine of your own, which our teams keep up to date and monitor day and night. Actual Budget is a local-first personal finance tool, released under the MIT license. This guide follows its official documentation: the role of the server, installing with Docker Compose, HTTPS, the server password, OpenID, end-to-end encryption, bank sync, backups and updates.
By Simon Vasconcelos Lee
Published on 17 November 202614 minute read
SharedArrayBuffer, which browsers only enable on a page served over HTTPS. A reverse proxy handles it.docker compose pull.Actual Budget is a local-first personal finance tool written in Node.js, which its README describes as entirely free and open source. It keeps all your data on each of your devices and syncs it in the background with the server you have chosen: the app works even without a connection, and your changes reach your other devices as soon as the network is back.
The project is made of a client and a server. The server is optional, but the documentation strongly recommends it, as it unlocks several features:
| Feature | Without a server | With a server |
|---|---|---|
| Budgets, reports, schedules | Yes | Yes |
| Importing transactions from a file | Yes | Yes |
| Importing and exporting budget files | Yes | Yes |
| The app in a browser and on a phone | Yes | |
| Sync between devices | Yes | |
| Bank sync | Yes | |
| The Actual API | Yes |
Actual Budget is released under the MIT license, copyright James Long. The text grants anyone who obtains a copy, free of charge, the right to use, copy, modify, merge, publish, distribute, sublicense and sell copies of it.
There is one condition: the copyright notice and the license text go with all copies or substantial portions of the software. You can therefore run the image published by the project for yourself, your family or your business, with no license to buy.
The project publishes the server as a Docker image, actualbudget/actual-server on Docker Hub, and the same image on GitHub’s registry, ghcr.io/actualbudget/actual. On a server with Docker installed, create a folder and put this compose.yaml in it, taken from the file provided in the repository:
services:
actual_server:
image: docker.io/actualbudget/actual-server:latest
container_name: actual_server
restart: unless-stopped
ports:
- 127.0.0.1:5006:5006
volumes:
- ./actual-data:/data
healthcheck:
test: ['CMD-SHELL', 'node scripts/health-check.js']
interval: 60s
timeout: 10s
retries: 3
start_period: 20s
docker compose up -d
127.0.0.1, it can only be reached through the reverse proxy on the same server, which adds HTTPS.actual-data folder holds everything the server keeps. It creates two subfolders there, server-files and user-files, and the documentation points out that this mount keeps your data when the container is removed.latest tag follows the most recent official release, and the documentation recommends it for most users. latest-alpine gives the same release on a lighter Alpine base, and a tag such as 26.11.0 pins a version. The nightly tags follow development, with every change to its main branch.Your domain name points to the server with A and AAAA records, and visitors arrive on ports 80 and 443. Until HTTPS is in place, the app does not open: go straight to the next section.
The project gives no memory or CPU figures. The size depends on the number of budgets, their history and the number of devices that sync. On a managed VPS, describe your use to us and we will recommend the right size.
Actual Budget relies on SharedArrayBuffer, a browser technology its documentation describes as required: without it, the app does not start. Browsers only enable it on an isolated page, which takes two conditions:
localhost.Cross-Origin-Embedder-Policy set to require-corp and Cross-Origin-Opener-Policy set to same-origin. The official server always sets them itself.To expose Actual to the internet, the documentation asks you to put it behind a reverse proxy with HTTPS. The server can also serve HTTPS itself with a certificate you give it, through ACTUAL_HTTPS_KEY and ACTUAL_HTTPS_CERT: the documentation describes this route for a server that stays off the internet.
The documentation presents Caddy as an easy reverse proxy, which obtains and renews its certificates on its own. Here is its example, adapted to Caddy installed on the server:
budget.example.com {
encode gzip zstd
reverse_proxy 127.0.0.1:5006
}
This block follows the documentation’s Nginx configuration, reduced to port 80 so that Certbot can set up HTTPS. It hides the two headers sent by Actual and sets them again, once: the documentation warns that a duplicated header invalidates the policy, and the app then stops on the SharedArrayBufferMissing error.
server {
listen 80;
listen [::]:80;
server_name budget.example.com;
client_max_body_size 0;
location / {
proxy_pass http://127.0.0.1:5006;
proxy_hide_header Cross-Origin-Embedder-Policy;
proxy_hide_header Cross-Origin-Opener-Policy;
add_header Cross-Origin-Embedder-Policy "require-corp" always;
add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Origin-Agent-Cluster "?1" always;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
client_max_body_size 0 lifts Nginx’s size limit, as in the documentation’s example, so a large budget file gets through to the server. Certbot then installs the certificate and takes care of renewing it:
sudo certbot --nginx
Open your address over https, in a new tab rather than by reloading a page that showed an error, as the documentation advises. Actual’s welcome screen appears: HTTPS and the headers are in place.
On first start, the welcome screen asks you to choose a password for the server: it is what protects access to your budgets. Until one is set, this screen shows to the first person who opens the address. So open it as soon as HTTPS works, and choose a long password used only for this server.
The server keeps this password hashed, with argon2, in the account.sqlite file of server-files, along with the list of budget files it knows and the active session token.
The documentation provides a command that sets a new password without touching your files or data. It asks for it twice:
docker exec -it actual_server node /app/src/scripts/reset-password.js
ACTUAL_LOGIN_METHOD: password by default, openid for an identity provider, or header.x-actual-password header. The documentation warns that a misconfiguration at this step could make the instance available to the whole internet: keep it for those services.ACTUAL_ALLOWED_LOGIN_METHODS, a comma-separated list.For authentication more robust than a password, the documentation recommends an OpenID provider: most of them offer two-factor authentication. It is also what opens the server to multiple users. The configuration reference presents this method as a preview.
https://budget.example.com/openid/callback.The same configuration can also go in config.json or in environment variables, with a discovery URL when the provider publishes one:
environment:
ACTUAL_OPENID_DISCOVERY_URL: "https://auth.example.com/.well-known/openid-configuration"
ACTUAL_OPENID_CLIENT_ID: "actual"
ACTUAL_OPENID_CLIENT_SECRET: ${ACTUAL_OPENID_CLIENT_SECRET}
ACTUAL_OPENID_SERVER_HOSTNAME: "https://budget.example.com"
The secret goes in a .env file next to compose.yaml. Since version 26.10.0, ACTUAL_OPENID_CLIENT_SECRET_FILE can also read it from a file, which suits Docker secrets.
"authMethod": "oauth2", in config.json.ACTUAL_USER_CREATION_MODE set to login creates them at their first login.ACTUAL_OPENID_ENFORCE set to true makes it the only accepted login method.ACTUAL_TOKEN_EXPIRATION is never by default. It can follow the provider’s, with openid-provider, or a duration in seconds.On top of the server password, each budget can be end-to-end encrypted. Its data is then encrypted on your device, with a key derived from a second password, before it leaves: the server only passes along changes it cannot read.
The documentation is clear: a forgotten encryption password cannot be recovered. If a local copy of the budget still exists, you can generate a new key, which resets sync. Encryption cannot be turned off either: going back to an unencrypted file goes through an export, then an import.
| Protection | What it brings | Where it is set |
|---|---|---|
| HTTPS | Encrypts the path between your devices and the server, and lets the app start | The reverse proxy |
| Server password | Restricts access to the budgets, hashed with argon2 on the server | On first start, then in the settings |
| OpenID | Your provider’s two-factor authentication, and one account per person | At the provider, then in the settings |
| End-to-end encryption | Makes budgets unreadable to the server and to its backups | In each budget |
| Disk encryption | Protects the local copy, which the documentation notes is unencrypted | On each of your devices |
End-to-end encryption covers budget data. Bank sync credentials are kept on the server, in account.sqlite, outside this encryption: protect access to the server and to its backups accordingly.
Actual imports your transactions from a file, with no setup. It can also fetch them directly from your bank, through a bank data provider. This sync is optional, needs the server, and relies on your own credentials: you open an account with the provider and create there the keys you give to Actual. These keys are kept on the server, and you only enter them once.
| Provider | Banks covered, per the documentation | Status at version 26.11.0 |
|---|---|---|
| SimpleFIN Bridge | North American banks | Supported; per-budget credentials possible since 26.11.0 |
| GoCardless Bank Account Data | European banks | Supported for existing accounts: GoCardless has not accepted new accounts since July 2025 |
| Pluggy.ai | Brazilian banks | Supported |
| Enable Banking | European banks | Experimental feature |
| Akahu | New Zealand banks | Experimental feature |
ACTUAL_SIMPLEFIN_ALLOWED_NETWORKS. Public SimpleFIN bridges need no setting.Each device keeps a full copy of your budgets, and the server keeps another. A good backup covers both: the server’s data folder, and an export of each budget.
| Item | What it holds | Back up |
|---|---|---|
server-files/account.sqlite | The hashed password, the list of budgets, sessions, OpenID accounts and bank credentials | Required, encrypted |
user-files/ | The budget files, as binary files | Required |
config.json | The server configuration, if you created one | Recommended, encrypted |
| Each budget’s export | A zip file with the db.sqlite database and metadata.json | Recommended |
Everything the server keeps lives in actual-data. With the server stopped, it can be copied in one go, its SQLite databases at rest:
docker compose down
tar -czf actual-$(date +%F).tar.gz actual-data
docker compose up -d
Schedule this copy on the server, encrypt it, and keep one elsewhere. Stored on the server’s disk, it is also part of its nightly backups.
From an open budget: Settings, Data section, Export data. The file can be kept wherever you like, and opens again without a server. The documentation uses this export to go back from an encrypted budget to an unencrypted file: it holds your data in the clear, so keep it somewhere safe.
An old budget gives a large export, because Actual keeps every change in the file. The documentation then advises Reset sync, in the advanced settings, before exporting: the history is compacted into a single file, and the size drops sharply.
On your other devices, then choose this budget in the file list: it downloads, then syncs. The desktop apps also keep their own automatic backups, one for each of the last ten days of use, and several for the current day.
The documentation gives the command, from the compose.yaml folder. The data folder stays in place:
docker compose pull
docker compose up -d
Versions are numbered by year and month: 26.11.0 came out on 1 November 2026, and the latest releases have been published at the start of each month. Read their notes before updating, and export your budgets just before, as the documentation recommends. The notes flag the changes to plan for, such as the list of allowed SimpleFIN networks in 26.11.0, or the Ubuntu image moving to Node.js 24 in 26.9.0, which dropped it from 32-bit ARM processors in favour of the Alpine image.
nightly tags: going back from nightly to latest can leave a budget unreadable for the stable release. The documentation describes the fix, and asks for backups of your budgets with these tags.Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; Actual Budget remains your software, with its settings and your budgets.
| Topic | Our teams | You |
|---|---|---|
| The server | System and security updates, server interventions included | The timing that suits your business |
| Monitoring | Server monitored 24/7, with intervention without waiting for your call | Reading your instance’s logs |
| Actual Budget | Proactive monitoring: errors, slowdowns and disk space spotted, fix recommended | Its installation, updates and settings, which you apply, yourself or through your AI assistant |
| Access and budgets | The server that carries them, monitored and backed up | The server password, OpenID, users and end-to-end encryption |
| Bank sync | The server that keeps its credentials, monitored and backed up | The choice of provider, its keys and the linked accounts |
| Backups | Every night, encrypted and kept off the machine; restores included | Your budget exports, and the restore request, when you need one |
| Migration | Your current server migrated, free of charge | The timing of the switch |
If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.
With a Simafri Managed VPS, our teams keep your Actual Budget instance’s server up to date, monitor it day and night and step in without waiting for your call; they also proactively monitor your instance and recommend useful fixes, which you apply, yourself or through your AI assistant. Backups are encrypted every night and kept off the machine, restores are included, and migrating your current server is free.
Yes. Actual Budget is released under the MIT license: you can use, modify and redistribute it freely, for yourself or for a business, as long as its copyright and license notice stays in the copies. What remains is the cost of the server that runs it.
The desktop apps work on their own. The server, which the documentation strongly recommends, adds the web and mobile app, sync between devices, bank sync and the API. Each device keeps a full copy of your budgets, synced with the server.
Create a compose.yaml with the actualbudget/actual-server image, port 5006 published on 127.0.0.1 and a data folder mounted on /data, then run docker compose up -d. Next, put an HTTPS reverse proxy in front, and open your address to choose the server password.
The app needs SharedArrayBuffer, which browsers only enable on a page served over HTTPS with the Cross-Origin-Embedder-Policy and Cross-Origin-Opener-Policy headers. The server sets these headers; the reverse proxy brings HTTPS. Only access through localhost does without it.
Serve the instance over HTTPS, choose a strong server password or use OpenID with two-factor authentication, and turn on end-to-end encryption: the server can no longer read your budgets. Keep that second password somewhere safe, as it cannot be recovered.
Yes, through a bank data provider, with your own credentials: SimpleFIN Bridge, GoCardless Bank Account Data for existing accounts, Pluggy.ai, and Enable Banking and Akahu as experimental features. Sync needs the server, and can run automatically since version 26.11.0.
Copy the server’s data folder with the server stopped: server-files holds the accounts and credentials, user-files the budgets. Also export each budget from Settings, Export data, and keep these copies encrypted. An export is restored with Import file.
A managed VPS covers the server: system, security, monitoring and backups. Our teams also proactively monitor your instance and recommend useful fixes, which you apply. Work inside the application is billed by the hour or at a fixed rate.
Simafri
Let's talk about your project
Tell us what you need in a few words: we will get back to you quickly.
Thank you! Your request has been sent. We'll get back to you shortly.
Prefer email? Write to us at support@simafri.com.