Self-host Actual Budget on a managed VPS: your budgets on your own server

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.

Simon Vasconcelos Lee By Published on 17 November 202614 minute read

All guides

In short

  1. The MIT license lets you use, modify and redistribute Actual Budget freely, as long as its copyright and license notice stays in the copies.
  2. The server syncs your budgets between your devices and serves the web app: install it with Docker Compose, one image and a data folder.
  3. HTTPS is essential: the app needs SharedArrayBuffer, which browsers only enable on a page served over HTTPS. A reverse proxy handles it.
  4. Open your address as soon as the server first starts to choose the server password. OpenID adds your provider’s two-factor authentication and multiple users.
  5. Optional end-to-end encryption makes your budgets unreadable to the server. Back up the data folder and export your budgets, then update with docker compose pull.

What Actual Budget does, and the role of its server

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:

FeatureWithout a serverWith a server
Budgets, reports, schedulesYesYes
Importing transactions from a fileYesYes
Importing and exporting budget filesYesYes
The app in a browser and on a phoneYes
Sync between devicesYes
Bank syncYes
The Actual APIYes

What the MIT license allows

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.

Installing with Docker Compose

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:

compose.yaml
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
Terminal
docker compose up -d

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.

HTTPS: a condition for the app to start

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:

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.

With Caddy

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:

Caddyfile
budget.example.com {
    encode gzip zstd
    reverse_proxy 127.0.0.1:5006
}

With Nginx and Certbot

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.

Nginx block
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:

Terminal
sudo certbot --nginx

Checking

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.

The server password

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.

Resetting a forgotten password

The documentation provides a command that sets a new password without touching your files or data. It asks for it twice:

Terminal
docker exec -it actual_server node /app/src/scripts/reset-password.js

OpenID and multiple users

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.

  1. Register Actual with your provider, with the redirect URI https://budget.example.com/openid/callback.
  2. In an open budget, go to the settings and click Start using OpenID, then fill in the provider, the client ID and its secret.
  3. Log in with OpenID. The documentation warns that the first person to log in becomes the server’s admin and owner, a role that can no longer be changed from the interface: make sure you log in first.

The same configuration can also go in config.json or in environment variables, with a discovery URL when the provider publishes one:

compose.yaml, in the service
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.

End-to-end encryption

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.

  1. Open the budget, go to the settings, Encryption section, and click Enable encryption.
  2. Choose a password different from the server password.
  3. On each other device, enter this same password once, when the budget is first downloaded.

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.

ProtectionWhat it bringsWhere it is set
HTTPSEncrypts the path between your devices and the server, and lets the app startThe reverse proxy
Server passwordRestricts access to the budgets, hashed with argon2 on the serverOn first start, then in the settings
OpenIDYour provider’s two-factor authentication, and one account per personAt the provider, then in the settings
End-to-end encryptionMakes budgets unreadable to the server and to its backupsIn each budget
Disk encryptionProtects the local copy, which the documentation notes is unencryptedOn 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.

Bank sync

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.

ProviderBanks covered, per the documentationStatus at version 26.11.0
SimpleFIN BridgeNorth American banksSupported; per-budget credentials possible since 26.11.0
GoCardless Bank Account DataEuropean banksSupported for existing accounts: GoCardless has not accepted new accounts since July 2025
Pluggy.aiBrazilian banksSupported
Enable BankingEuropean banksExperimental feature
AkahuNew Zealand banksExperimental feature

Backups

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.

ItemWhat it holdsBack up
server-files/account.sqliteThe hashed password, the list of budgets, sessions, OpenID accounts and bank credentialsRequired, encrypted
user-files/The budget files, as binary filesRequired
config.jsonThe server configuration, if you created oneRecommended, encrypted
Each budget’s exportA zip file with the db.sqlite database and metadata.jsonRecommended

The server folder

Everything the server keeps lives in actual-data. With the server stopped, it can be copied in one go, its SQLite databases at rest:

Terminal, in the compose.yaml folder
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.

Each budget’s export

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.

Restoring

  1. Close the open budget: click its name in the top left, then Switch file.
  2. Click Import file, choose Actual, then the export’s zip file.
  3. The imported budget appears next to the original: check it, rename it if needed, then delete the old copy.

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.

Updates

The documentation gives the command, from the compose.yaml folder. The data folder stays in place:

Terminal
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.

Who does what on a managed VPS

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.

TopicOur teamsYou
The serverSystem and security updates, server interventions includedThe timing that suits your business
MonitoringServer monitored 24/7, with intervention without waiting for your callReading your instance’s logs
Actual BudgetProactive monitoring: errors, slowdowns and disk space spotted, fix recommendedIts installation, updates and settings, which you apply, yourself or through your AI assistant
Access and budgetsThe server that carries them, monitored and backed upThe server password, OpenID, users and end-to-end encryption
Bank syncThe server that keeps its credentials, monitored and backed upThe choice of provider, its keys and the linked accounts
BackupsEvery night, encrypted and kept off the machine; restores includedYour budget exports, and the restore request, when you need one
MigrationYour current server migrated, free of chargeThe 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.

Actual Budget, on a server run for you

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.

Explore Managed VPS

Frequently asked questions

Is Actual Budget 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.

Do I need a server to use Actual Budget?

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.

How do I install Actual Budget with Docker Compose?

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.

Why does Actual Budget require HTTPS?

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.

How do I protect the data in an Actual budget?

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.

Does Actual Budget connect to my bank?

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.

How do I back up Actual Budget?

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.

Does a managed VPS cover Actual Budget?

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.

Contact us