1. Project Overview & Quickstart (actualbudget/actual)

File: README.md

Getting Started

Actual is a local-first personal finance tool. It is 100% free and open-source, written in NodeJS, it has a synchronization element so that all your changes can move between devices without any heavy lifting.

If you are interested in contributing, or want to know how development works, see our contributing document we would love to have you.

Want to say thanks? Click the ⭐ at the top of the page.

Key Links

Installation

There are four ways to deploy Actual:

One-click deployment via PikaPods (~2.00 $/month) - recommended for non-technical users
Managed hosting via Fly.io (~1.50 $/month)
Self-hosted by using a Docker image
Local-only apps - downloadable Windows, Mac and Linux apps you can run on your device

Learn more in the installation instructions docs.

Ready to Start Budgeting?

Read about Envelope budgeting to know more about the idea behind Actual Budget.

Are you new to budgeting or want to start fresh?

Check out the community's Starting Fresh guide so you can quickly get up and running!

Are you migrating from other budgeting apps?

Check out the community's Migration guide to start jumping on the Actual Budget train!

Documentation

We have a wide range of documentation on how to use Actual, this is all available in our Community Documentation, this includes topics on Budgeting, Account Management, Tips & Tricks and some documentation for developers.

Contributing

Actual is a community driven product. Learn more about contributing to Actual.

Code structure

The Actual app is split up into a few packages:

loot-core - The core application that runs on any platform
desktop-client - The desktop UI
desktop-electron - The desktop app

More information on the project structure is available in our community documentation.

Feature Requests

Current feature requests can be seen here.
Vote for your favorite requests by reacting :+1: to the top comment of the request.

To add new feature requests, open a new Issue of the "Feature Request" type.

Translation

Make Actual Budget accessible to more people by helping with the Internationalization of Actual. We are using a crowd sourcing tool to manage the translations, see our Weblate Project. Weblate proudly supports open-source software projects through their Libre plan.

Repo Activity

File: packages/sync-server/src/app-gocardless/README.md

Integration new bank

If the default bank integration does not work for you, you can integrate a new bank by following these steps.

Find the identifier of the bank which you want to integrate. Note: the reference sheet that previously contained bank identifiers no longer exists.
Launch frontend and backend server.
In the frontend, create a new linked account selecting the institution which you are interested in.

This will trigger the process of fetching the data from the bank and will log the data in the backend. Use this data to fill the logic of the bank class.
Create new a bank class based on an existing example in app-gocardless/banks.

Name of the file and class should follow the existing patterns and be created based on the ID of the integrated institution, found in step 1.

Fill the logic of normalizeAccount, normalizeTransaction, sortTransactions, and calculateStartingBalance functions.
You do not need to fill every function, only those which are necessary for the integration to work.

You should do it based on the data which you found in the logs.

Example logs which help you to fill:

normalizeAccount function:

log

Available account properties for new institution integration {
  account: '{
    "iban": "PL00000000000000000987654321",
    "currency": "PLN",
    "ownerName": "John Example",
    "displayName": "Product name",
    "product": "Daily account",
    "usage": "PRIV",
    "ownerAddressUnstructured": [
      "POL",
      "UL. Example 1",
      "00-000 Warsaw"
    ],
    "id": "XXXXXXXX-XXXX-XXXXX-XXXXXX-XXXXXXXXX",
    "created": "2023-01-18T12:15:16.502446Z",
    "last_accessed": null,
    "institution_id": "MBANK_RETAIL_BREXPLPW",
    "status": "READY",
    "owner_name": "",
    "institution": {
      "id": "MBANK_RETAIL_BREXPLPW",
      "name": "mBank Retail",
      "bic": "BREXPLPW",
      "transaction_total_days": "90",
      "countries": [
        "PL"
      ],
      "logo": "https://cdn.nordigen.com/ais/MBANK_RETAIL_BREXCZPP.png",
      "supported_payments": {},
      "supported_features": [
        "access_scopes",
        "business_accounts",
        "card_accounts",
        "corporate_accounts",
        "pending_transactions",
        "private_accounts"
      ]
    }
  }'
}

sortTransactions function:

log

Available (first 10) transactions properties for new integration of institution in sortTransactions function
{
  top10SortedTransactions: '[
    {
      "transactionId": "20220101001",
      "bookingDate": "2022-01-01",
      "valueDate": "2022-01-01",
      "transactionAmount": {
        "amount": "5.01",
        "currency": "EUR"
      },
      "creditorName": "JOHN EXAMPLE",
      "creditorAccount": {
        "iban": "PL00000000000000000987654321"
      },
      "debtorName": "CHRIS EXAMPLE",
      "debtorAccount": {
        "iban": "PL12345000000000000987654321"
      },
      "remittanceInformationUnstructured": "TEST BANK TRANSFER",
      "remittanceInformationUnstructuredArray": [
        "TEST BANK TRANSFER"
      ],
      "balanceAfterTransaction": {
        "balanceAmount": {
          "amount": "448.52",
          "currency": "EUR"
        },
        "balanceType": "interimBooked"
      },
      "internalTransactionId": "casfib7720c2a02c0331cw2"
    }
  ]'
}

calculateStartingBalance function:

log

Available (first 10) transactions properties for new integration of institution in calculateStartingBalance function {
  balances: '[
    {
      "balanceAmount": {
        "amount": "448.52",
        "currency": "EUR"
      },
      "balanceType": "forwardAvailable"
    },
    {
      "balanceAmount": {
        "amount": "448.52",
        "currency": "EUR"
      },
      "balanceType": "interimBooked"
    }
  ]',
    top10SortedTransactions: '[
    {
      "transactionId": "20220101001",
      "bookingDate": "2022-01-01",
      "valueDate": "2022-01-01",
      "transactionAmount": {
        "amount": "5.01",
        "currency": "EUR"
      },
      "creditorName": "JOHN EXAMPLE",
      "creditorAccount": {
        "iban": "PL00000000000000000987654321"
      },
      "debtorName": "CHRIS EXAMPLE",
      "debtorAccount": {
        "iban": "PL12345000000000000987654321"
      },
      "remittanceInformationUnstructured": "TEST BANK TRANSFER",
      "remittanceInformationUnstructuredArray": [
        "TEST BANK TRANSFER"
      ],
      "balanceAfterTransaction": {
        "balanceAmount": {
          "amount": "448.52",
          "currency": "EUR"
        },
        "balanceType": "interimBooked"
      },
      "internalTransactionId": "casfib7720c2a02c0331cw2"
    }
  ]'
}

Add new bank integration to BankFactory class in file actual-server/app-gocardless/bank-factory.js
Remember to add tests for new bank integration in

normalizeTransaction

This is the most commonly used override as it allows you to change the data that is returned to the client.

Please follow the following patterns when implementing a custom normalizeTransaction method:

If you need to edit the values of transaction fields (excluding the transaction amount) do not mutate the original transaction object. Instead, create a shallow copy and make your changes there.
End the function by returning the result of calling the fallback normalizeTransaction method from integration-bank.js

E.g.

import Fallback from './integration-bank';

export default {
  ...

  normalizeTransaction(transaction, booked) {
    // create a shallow copy of the transaction object
    const editedTrans = { ...transaction };

    // make any changes required to the copy
    editedTrans.remittanceInformationUnstructured = transaction.remittanceInformationStructured;

    // call the fallback method, passing in your edited transaction as the 3rd parameter
    // this will calculate the date, payee name and notes fields based on your changes
    // but leave the original fields available for mapping in the UI
    return Fallback.normalizeTransaction(transaction, booked, editedTrans);
  }

  ...
}

File: packages/sync-server/README.md

This is the main project to run Actual, a local-first personal finance tool. It comes with the latest version of Actual, and a server to persist changes and make data available across all devices.

Getting Started

If you are interested in contributing, or want to know how development works, see our contributing document we would love to have you.

Want to say thanks? Click the ⭐ at the top of the page.

Using the CLI tool

Node.js v22 or higher is required for the @actual-app/sync-server npm package

Install globally with npm:

bash

npm install --location=global @actual-app/sync-server

After installing, you can execute actual-server commands directly in your terminal.

Usage

bash

actual-server [options]

Available options

Command	Description
`-h` or `--help`	Print this list and exit.
`-v` or `--version`	Print this version and exit.
`--config`	Path to the config file.
`--reset-password`	Reset your password

Examples

Run with default configuration

bash

actual-server

Run with custom configuration

bash

actual-server --config ./config.json

Reset your password

bash

actual-server --reset-password

Documentation

We have a wide range of documentation on how to use Actual. This is all available in our Community Documentation, including topics on installing, Budgeting, Account Management, Tips & Tricks and some documentation for developers.

Feature Requests

Current feature requests can be seen here. Vote for your favorite requests by reacting 👍 to the top comment of the request.

To add new feature requests, open a new Issue of the "Feature Request" type.

File: packages/desktop-client/README.md

Actual on the web

E2E tests

E2E (end-to-end) tests use Playwright. Running them requires an Actual server to be running either locally or on a remote server.

Functional

Running against the local server:

# Start the development server
yarn start

# Run against the local server (localhost:3001)
yarn e2e

Running against a remote server:

E2E_START_URL=http://my-remote-server.com yarn e2e

Visual regression

Visual regression tests (also known as screenshot tests) check that the visual appearance of the product has not regressed. Each environment has slightly different colors, fonts etc. Mac differs from Windows which differs from Linux. In order to have a stable test environment for visual comparisons - you must use a standartised docker container. This ensures that the tests are always ran in a consistent environment.

Prerequisites:

Docker installed

Running against the local server

First start a dev instance:

HTTPS=true yarn start

or using the dev container:

text

HTTPS=true docker compose up --build

Note the network IP address and port the dev instance is listening on.

Next, navigate to the root of your project folder, run the standardized docker container, and launch the visual regression tests from within it.

Run via yarn:

# By default, this connects to https://localhost:3001
yarn vrt:docker

    # To use a different ip and port:
    yarn vrt:docker --e2e-start-url https://ip:port

    # To update snapshots, use the following command:
    yarn vrt:docker --e2e-start-url https://ip:port --update-snapshots

Run manually:

# Run docker container
docker run --rm --network host -v $(pwd):/work/ -w /work/ -it mcr.microsoft.com/playwright:v1.61.1-jammy /bin/bash

    # If you receive an error such as "docker: invalid reference format", please instead use the following command:
    docker run --rm --network host -v ${pwd}:/work/ -w /work/ -it mcr.microsoft.com/playwright:v1.61.1-jammy /bin/bash

# Once inside the docker container, run the VRT tests: important - they MUST be ran against a HTTPS server.
# Use the ip and port noted earlier
E2E_START_URL=https://ip:port yarn vrt

    # To update snapshots, use the following command:
    E2E_START_URL=https://ip:port yarn vrt --update-snapshots

Running against a remote server

You can also run the tests against a remote server by passing the URL:

Run in standardized docker container:

E2E_START_URL=https://my-remote-server.com yarn vrt:docker

    # Or pass in server URL as argument
    yarn vrt:docker --e2e-start-url https://my-remote-server.com

Run locally:

E2E_START_URL=https://my-remote-server.com yarn vrt

File: packages/crdt/README.md

`@actual-app/crdt`

This package contains the core CRDT logic that enables Actual's syncing. It is shared between the client and server. We may or may not follow semver when updating this package; any usage of it outside Actual is undocumented and at your own risk.

protobuf

We use protobuf to encode messages as binary data to send across the network.

Generating protobuf

The protobuf is generated by using the protoc compiler.

This can be installed by downloading one of the pre-built binaries and placing it in your $PATH. The version used to build the current protobuf is v3.20.1. You'll also need to download the latest version of protoc-gen-js. For convenience, you can put both of these binaries in ./bin.

Once installed, the protobuf can be generated by running ./bin/generate-proto.

However there is one very important thing to remember! The default output includes this near the top:

text

var global = (function() { return this || window || global || self || Function('return this')(); }).call(null);

This will not work with our CSP directives. You must manually modify this to this:

text

var global = globalThis;

File: packages/api/README.md

text

npm install @actual-app/api

View docs here: https://actualbudget.org/docs/api/

TypeScript

@actual-app/api publishes TypeScript declarations. Consumers using TypeScript must set moduleResolution to "bundler", "nodenext", or "node16" in their tsconfig.json. Legacy "node" / "node10" / "classic" resolution is not supported in strict mode — the published declarations rely on package.json exports conditions that older resolvers don't honor.

File: upcoming-release-notes/README.md

See the Writing Good Release Notes section of the README for the documentation repo for more information on how to create a release notes file here.

2. Official Technical Reference & Guides (actualbudget/docs)

File: README.md

[!IMPORTANT]
This repository has been merged into actualbudget/actual in November 2025 and placed in a readonly state. If you'd like to contribute to the Actual documentation, please open your change in the main repository.

Actual Budget Community Documentation

This repo is the Actual Budget community documentation website, built using Docusaurus 3, a modern static website generator.

Docusaurus 3 uses Node.js, so if you are running Actual on your local machine, you should be able to easily run Docusaurus 3.

Welcome

Firstly, thank you for stopping by and giving up some of your time to either check out the documentation we have already produced or pick off
some of the issues and help create some new documentation for our future users. Check out the
guidelines for more information on how the documentation is structured and tips for consistent formatting.

Installation Methods

Actual Budget can be installed on many different platforms. However, at this time, the official Actual Budget documentation only supports the following methods:

Local Installation (on your own machine)
- Actual-server
- Desktop apps
Fly.io
PikaPods
Docker

If you would like to write documentation for another installation variant, please feel free to continue to do this and host it on your own personal blog, Medium, Tumblr, or any other short-form publication service. We will be more than happy to add a link to that from our documentation. Open a PR and add it to the list in the installation overview.

However, in doing so, you would become responsible for these instructions. If they become out of date or people want in-depth help with them, we will point them to you for assistance if the community is unable to help. If lots of people report issues with them, we may have to remove the link altogether.

Contributing

Please review the contributing documentation on our website: https://actualbudget.org/docs/contributing/

Issues

If you know of a part of Actual that isn't documented and you would like to know more about that part of the software, open an Issue and one of the documentation team will get to it. Or have a go at writing it yourself; we could really use all the help we can get.

Pull Requests

When submitting a pull request, please make sure that your contributions are complete. I am checking this repo regularly, so if I see an open PR, the likelihood of me pulling it and merging it is high.

Documentation submitted will be proofread and amended before merging. Please don't take this personally if any of your documentation gets amended; we just want to make sure all documents are ready to go before merging them into master.

Installing the Docs

Firstly, pull this repo into a local area on your machine, navigate to that directory, and run the following command:

text

$ yarn

Local Development

To start Docusaurus 3 navigate to the folder where the repo resides from a command prompt and issue the following command.

text

$ yarn start

This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

Build

text

$ yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Deployment

Using SSH:

text

$ USE_SSH=true yarn deploy

Not using SSH:

text

$ GIT_USER=<Your GitHub username> yarn deploy

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

Writing Good Release Notes

For general guidelines, see Contributing section of the documentation. The Documentation site is not versioned in the same manner as the rest of the project. The Documentation website is more of a living document. Merges into master will have the title and PR# as commit message, with the PR description as extended git commit description.

File: docs/accounts/index.md

Overview

You can add as many accounts as you like. Adding all of your accounts (including things like mortgages) is a nice way to get an overview of all your finances.

Off budget accounts

Actual makes a distinction between accounts being on budget or off budget. Off budget accounts don't affect the budget and are meant to track stuff like investments and mortgages. Transactions in off budget accounts can't be categorized; they simply track balances over time.

Off budget accounts don't affect the budget and are meant to track stuff like investments and mortgages. Transactions in off budget accounts can't be categorized; they simply track balances over time.

On budget accounts affect the budget, and transactions can be categorized. These are accounts where you want to track cash flow and use the budget, like checking accounts and credit cards.

Depending on your usage, savings accounts can be on or off the budget. If you're not sure, we recommend keeping them on budget at the start.

Adding a new account

You can add an account to your budget at any time, however when you first install Actual you can use the Add Account button in the middle of the screen.

You can also add an account using the + Add account button in the sidebar.

Two successive screens will appear with boxes asking you to fill in a few options

Create a Local Account or Link to a supported bank syncing provider (See Connecting Your Bank)
Give your account a name
Is the account on budget or off budget
The current account balance

:::note
Off budget means that the balance is not reflected when you assign money to categories in your budget register
:::

Here you can see how that looks when the options are completed.

:::note
If you select the Off budget checkbox then change the account type, the Off budget checkbox will reset and will need to be re-selected each time the account type is changed.
:::

You can now see the account in the sidebar of Actual

Closing or deleting an account

Navigate to the account by clicking on it in the sidebar
Click on the 3 dots (top right of the transactions list) to show the actions menu
Select Close Account
You need to select another account to transfer the existing balance to. Choose the account that you have moved funds to.
Press Close Account

You can still access this account under Closed Accounts in the sidebar, and even reopen it from the same actions menu.

If you want to delete an account even if it has existing balances, in the popup after selecting Close Account, click the force close at the bottom.

Renaming an existing account

Click the account name in the sidebar of Actual

Hovering your cursor close to the account name at the top will reveal two icons.
The page icon allows you to write a note about this account, and the pencil icon allows you to rename the account.

After editing a note for the account or its name, hit 'Enter' to save your changes.

File: docs/accounts/reconciliation.md

Reconciliation

Keeping your Actual account ledgers consistent with your bank ledgers is important to maintain a healthy budget and know exactly how much currency is available to spend. Some choose to reconcile monthly, weekly, or even daily. Actual provides the Reconciliation tool to help manage this process.

Work Flow

When you reconcile, you will be comparing your bank statement, print or online, against Actual's ledger for that account. If you have made transactions against the budget that have not been verified against your account the cleared flag will be shown in gray. If the transaction has been moved out of the pending section of your (online) bank statement, click the gray circle to turn it green. This is a visual indication that the transaction is in both your budget and in your account statement, and they match.

By clicking on the green balance in the header of the account view, two more category balances will come into view. The cleared total only includes transactions that have been cleared while the uncleared total will represent the transactions you have entered but may not have entered the bank statement yet.

Starting the Reconciliation Tool

Click the 🔒 lock icon in the top right-hand corner of the account ledger.

Let's imagine that we have just checked our account balance for our Ally Savings account and the current balance is 3012.13. We enter the balance we want to match into the Reconciliation tool and press Reconcile.

The tool will tell us exactly how much is different than the budget ledger. Now we can check the Actual ledger against the bank ledger and watch the difference come closer to 0 as you change the cleared status of transactions. In this case, we're looking for transactions that add up to 324.82. This is much easier by looking at the Actual ledger and bank statement side by side to match the transactions.

When the cleared amount of the Actual account ledger and the value you entered into the Reconciliation tool are the same, the tool will let you know that you are reconciled and you can press done.

Upon pressing done, all cleared transactions will receive a lock icon. This represents the fact that they were included in a reconciliation and makes it harder to accidentally change.

Of course, there's always the possibility you need to change a locked transaction. You can click on the lock of any transaction to open a dialog to unlock it.

Using the Reconciliation Tool for Off Budget Asset Tracking

Some people use off budget accounts to track values of assets such as vehicles, real estate, retirement accounts, or other investment accounts or property. The reconciliation tool is useful to update these values as well. Let's say we have a house that was valued at 367,800 but with current changes in the market it is now valued at 385,000. We go to the ledger for the house, choose the reconciliation tool, and enter 385,000 as the new value into the tool.

The tool tells us that we have a gain of 17,200.

We can use the "Create reconciliation transaction" button to easily create a new transaction that brings the value of the account in line with the new valuation. You should now have a reconciliation tool that is reporting that it is finished and you can enjoy a new higher net worth.

File: docs/advanced/bank-sync/gocardless.md

GoCardless Setup

:::note
Client Version 23.7.0 and
Server Version 23.7.0 or higher are required for this feature.
:::

:::warning
From July 2025 onwards, GoCardless has stopped accepting new Bank Account Data accounts. The below sign up instructions are now outdated, however, if you are an existing user, your account should continue to work.
:::

Create SECRET and KEY for Actual

Create an account with GoCardless - https://bankaccountdata.gocardless.com/overview/.
Log into your account dashboard at the same URL and select Developers->User secrets from the left side menu.
Click on the '+ create new' button at the bottom left.
- Make sure you download your secrets file since the key will not be available to you again in the account dashboard
- These secrets will be used in Actual to make the bank sync connection
Enter a name for your secrets and click Create.
This is only for you to easily identify them in the GoCardless User secrets overview
Download this file and keep it on your computer.
Back in Actual, click on “+ Add account” at the bottom of the sidebar.
Click “Set-up GoCardless for bank-sync.”
You will be asked to enter your GoCardless secret ID and secret key. These values will be saved on the server, so you will only need to enter them once.

Link Accounts with GoCardless

Add the link to your accounts in actual (Existing or New).
- For an existing account, click on that account, select the ... (kebab menu) in the top right, and choose Link Account
- To create a new account with bank syncing click on the '+ Add account' link in the left menu at the bottom
Select the Link your bank account button.
Select your country and bank from the list and click the Link bank in browser button.
Clicking Link bank in browser will redirect you to a new tab to grant access to your bank for GoCardless.
Select I agree to continue with setting up the connection.
If your connection was a success, you will be able to click on the continue button which allows GoCardless to connect.
A progress indicator will display while GoCardless connects to your bank to get a list of your accounts.
Once the connection has been made, there will be a list of your accounts that you can choose from.
The final step is to select the account you want to sync and click Link account.

Frequently Asked Questions

Does Actual sync automatically with your Bank?

At this moment, it is not yet possible for Actual to automatically sync with your bank. You need to do this manually by going to "All Accounts" and pressing "Sync".

The best way to start from scratch in Actual with GoCardless?

If you are setting up Actual for the first time, it is much easier not to try to pull in historic data. This has caused some users a lot of headaches with subsequent reconciliation. The following process may be more helpful:

Set up your account in Actual specifying a correct opening account balance at a recent date.
Link the account to GoCardless as above
Sync the account with GoCardless. You should find that only transactions subsequent to the opening account balance entry are imported, making reconciliation easy.

How many times can I sync with GoCardless?

In the free tier, you can connect up to 50 banks per month. If one of your banks include more than one account inside (like credit and debit cards), it will still be counted as one connection.
Every day you can sync each bank up to 4 times and there is no monthly limit though, just the daily one.
For more information, see the Bank Account Data API Usage
topic in the GoCardless FAQ.

File: docs/advanced/bank-sync/simplefin.md

SimpleFIN Setup

:::note
Client Version 24.10.0 and
Server Version 24.10.0 or higher are required for this feature.
:::

Generate Setup Token for Actual

Create an account with SimpleFIN Bridge - https://beta-bridge.simplefin.org/ , by clicking "Get Started" and entering your email address.
You will receive an email with the login link, after a few minutes. Click this link to log into your account dashboard.
Accept the terms, on first login, and then you will be taken to "My Account".
Link any banks that you wish.
- You will need to add your accounts first, through "Financial Institutions" > New Connection
- You will need to subscribe before your first can be added. Current rates are $1.50 / mo, or $15 / year.
From the "My Accounts" page, under "Apps", click on "New Connection". Give your connection a name, and click "Create Setup Token"

This is only for you to easily identify it in the SimpleFIN connections overview.
Save the generated Setup Token someplace safe (one-time use only).
Back in Actual, click on “+ Add account” at the bottom of the sidebar.
Click “Link bank account with SimpleFIN”.
You will be asked to enter your SimpleFIN setup token. The keys from this value will be saved on the server, so you will only need to enter it once.

Link Accounts with SimpleFIN

Add the link to your accounts in actual (Existing or New).
- For an existing account, click on that account, select the ... (kebab menu) in the top right, and choose Link Account
- To create a new account with bank syncing click on the '+ Add account' link in the left menu at the bottom
Select the Link bank account with SimpleFIN button.
A Link Accounts box will pop up. To link a SimpleFIN account to an Actual account, click the "Setup bank-sync" button in the same row.
- The "Bank Account To Sync" column contains the names of the accounts found via SimpleFIN
- The "Account in Actual" column contains the name of the Actual account it is linked to.
- You can also click in the "Account in Actual" column, instead of clicking the "Setup bank-sync" button.
Either select an existing Actual account to link to, or create a new one.
When you've mapped all your accounts that you wish to, click the "Link Account" button.

SimpleFIN Considerations

Currently, the sync pulls at most 90 days of data from each linked account. The amount of data SimpleFIN can get from each account may vary, so not all accounts may have 90 days of historical transactions that can be imported.
SimpleFIN's data updates one time / day, roughly every 24 hours, for each linked account. The time of day that each bank updates in SimpleFIN may vary, even from day to day (based on the bank and upstream provider, MX).

Resetting the Setup Token

To reset your SimpleFIN setup token:

Click "Add Account" in the sidebar.
Next to "Link bank account with SimpleFIN", click the three-dot menu button.
Click "Reset SimpleFIN credentials".

You will then need to obtain a new setup token from SimpleFIN and enter it into Actual.

File: docs/advanced/scripts/modify-transfers.md

Identify and Apply Transfers Historically

These SQL scripts modify transactions as to apply transfers historically over migrated data without duplicating transactions. This is useful when you have migrated multiple accounts.

:::caution
Before executing any actions, make sure you have a complete backup.
:::

:::note
This process will only apply when the below conditions are met

The two transactions are related to different accounts
The amounts are exactly the same but inverted e.g. -1.00 and 1.00
The transaction dates are within 3 days of each other
The match only occurs once. This means transfers of equal value following the pattern below will not be applied.
text
```
`Account A` -> `Account B` -> `Account A/C`

As we cannot reliably tell the order of the transfers.
```

:::

How To

Create a second copy of the backup
Extract the backup
Open the db.sqlite file with your preferred tool SQLite3 cli, heidiSQL, etc.
Run the below query to first view the impacted transactions
text

/* Detailed source-code truncated for AI context efficiency. */

text

5. Run the below query to update the transactions

/* Detailed source-code truncated for AI context efficiency. */

text

6. Zip the `db.sqlite` file with the original `metadata.json` file
7. Follow the [restore](../../backup-restore/restore.md) process to apply these into your Actual Server instance
8. Verify your balances are correct and you see the correct transactions marked as transfers!

---

## File: docs/advanced/bank-sync.md

# Connecting Your Bank

We are excited to offer optional bank integration in Actual.
Here are a couple of considerations to know about before making the decision to use bank sync in your installation of Actual Budget.

- This integration relies on you providing your own API credentials that you will need to get by signing up with the service provider and Generate Keys and Secrets that will be used in Actual.

- The integration only works if you are using actual-server.

- The Secrets and Keys are stored in your Actual installed version so it is highly recommended to turn on End to End encryption and create a strong passphrase to encrypt your files.

- You will need to add a config file to your installation.

## Supported Providers

* GoCardless [BankAccountData](/docs/advanced/bank-sync/gocardless/) (European Banks, **not accepting new accounts**)
* [SimpleFIN Bridge](/docs/advanced/bank-sync/simplefin) (North American Banks)
* Pluggy.ai (Brazilian Banks - [**Experimental feature**](/docs/experimental/pluggyai))

### Retrieve Transactions

Actual does **not** sync bank data automatically. To fetch new transactions manually:

- To sync all accounts: click **All Accounts** in the sidebar, then click **Bank Sync**.
- To sync a single account: open the account and click the Bank Sync button.

---

## File: docs/advanced/http-header-auth.md

# Authenticating With HTTP Headers

:::note
Client Version 24.6.0 and
Server Version 24.6.0 or higher are required for this feature.
:::

This feature will allow Actual to use an HTTP header to automatically authenticate and log in without prompting for a password. This is useful for individuals who run SSO services like [Authentik](https://goauthentik.io/), [Authelia](https://www.authelia.com/), and more.

## Setup

This feature needs to be enabled on the server, it is not configured to work out of the box. In the Actual config, set the value `loginMethod` or env `ACTUAL_LOGIN_METHOD` to `"header"`. This will enable header authentication, but the normal password authentication will still work as a fallback.

:::warning
Be careful! A misconfiguration on this next step could make your instance available to the whole internet.
:::

The SSO provider then needs to be configured to pass an extra HTTP header to Actual. The details on how to do this are unique to the SSO provider, but the header `x-actual-password` needs to be set to your actual password.


If your setup needs it, it is possible to configure trusted proxies for authentication. See [`trustedAuthProxies` configuration](../config/index.md#trustedAuthProxies) for details.

:::note
This feature is not an HTTP basic auth, but a different form of using a password. For HTTP basic auth or user accounts see [this issue](https://github.com/actualbudget/actual/issues/524)
:::

---

## File: docs/advanced/index.md

# Advanced Overview

:::caution
Pages in this area contain non-standard actions. Ensure backups and recovery are possible before taking any actions.
:::

---

## File: docs/advanced/restart.md

# Restarting Your Budget

If you've fallen behind on your budgeting and want to start fresh without starting from scratch.

This means that you want to reset your budget while keeping your categories, payees, rules and schedules. Below we have described two methods to restart your budget: one by deleting all transactions and another without deleting any transactions.

If you're ok with truly starting completely from scratch, [just make a new file](/docs/getting-started/starting-fresh/).

:::caution
Remember to [back up your budget](/docs/backup-restore/backup) before making any significant changes to your budget.
:::


## Restarting Your Budget by Deleting Transactions

### Step 1: Delete All Transactions
- Click on *All Accounts* in the left sidebar.
- Select all transactions by clicking the checkbox at the top of the list (or use the shortcut `Ctrl + A` on Windows or `Cmd + A` on Mac).
- Click on the lilac dropdown menu at the top of the transaction list and select **Delete**.




### Step 2: Set Starting Balances
- Go to each account and set the starting balance for today's date to the current amount in that account.

### Step 3: Adjust Previous Months' Category Balances
- Navigate to the month prior to your new start (e.g., the end of May, if the month you're restarting from is June).
- Review each budget category:
  - If a category has a **negative balance**, allocate additional funds to bring the balance to zero.
  - If a category has a **positive balance**, click on the category and transfer the balance amount back to the **"To Budget"** area.


## Restarting Your Budget Without Deleting Transactions

### Step 1: Address Uncategorized Transactions

- Go through any transactions that haven't been categorized.
- If you're unsure where to assign certain transactions, create a temporary category named **"Budget Reset"**.
- Once you've categorized all transactions, you can hide this temporary category.

### Step 2: Reconcile Your Accounts

Using the **Reconcile** feature, bring your accounts up to date with a current balance. This ensures that your accounts reflect the actual available funds.

### Step 3: Adjust Previous Months' Category Balances

- Navigate to the month prior to your new start (e.g., the end of May, if the month you're restarting from is June).
- Review each budget category:
  - If a category has a **negative balance**, allocate additional funds to bring the balance to zero.
  - If a category has a **positive balance**, click on the category and transfer the balance amount back to the **"To Budget"** area.

Docker & Self-Hosted Deployment Verified OCI

1. Project Overview & Quickstart (actualbudget/actual) Copy Chapter

File: README.md Copy Chapter

Getting Started Copy Chapter

Key Links Copy Chapter

Installation Copy Chapter

Ready to Start Budgeting? Copy Chapter

Are you new to budgeting or want to start fresh? Copy Section

Are you migrating from other budgeting apps? Copy Section

Documentation Copy Chapter

Contributing Copy Chapter

Code structure Copy Section

Feature Requests Copy Section

Translation Copy Section

Repo Activity Copy Chapter

Sponsors Copy Chapter

File: packages/sync-server/src/app-gocardless/README.md Copy Chapter

Integration new bank

normalizeTransaction Copy Chapter

File: packages/sync-server/README.md Copy Chapter

Getting Started Copy Section

Using the CLI tool Copy Section

Documentation Copy Section

Feature Requests Copy Section

File: packages/desktop-client/README.md Copy Chapter

E2E tests Copy Chapter

Functional Copy Section

Visual regression Copy Section

Running against the local server

Running against a remote server

File: packages/crdt/README.md Copy Chapter

`@actual-app/crdt`

protobuf Copy Chapter

Generating protobuf Copy Section

File: packages/api/README.md Copy Chapter

TypeScript Copy Chapter

File: upcoming-release-notes/README.md Copy Chapter

2. Official Technical Reference & Guides (actualbudget/docs) Copy Chapter

File: README.md Copy Chapter

Actual Budget Community Documentation

Welcome Copy Chapter

Installation Methods Copy Section

Contributing Copy Chapter

Issues Copy Section

Pull Requests Copy Section

Installing the Docs Copy Section

Local Development Copy Section

Build Copy Section

Deployment Copy Section

Writing Good Release Notes Copy Section

File: docs/accounts/index.md Copy Chapter

Overview

Off budget accounts Copy Chapter

Adding a new account Copy Chapter

Closing or deleting an account Copy Chapter

Renaming an existing account Copy Chapter

File: docs/accounts/reconciliation.md Copy Chapter

Reconciliation

Work Flow Copy Chapter

Starting the Reconciliation Tool Copy Chapter

Using the Reconciliation Tool for Off Budget Asset Tracking Copy Chapter

File: docs/advanced/bank-sync/gocardless.md Copy Chapter

GoCardless Setup

Create SECRET and KEY for Actual Copy Section

Link Accounts with GoCardless Copy Section

Frequently Asked Questions Copy Section

File: docs/advanced/bank-sync/simplefin.md Copy Chapter

SimpleFIN Setup

Generate Setup Token for Actual Copy Section

Link Accounts with SimpleFIN Copy Section

SimpleFIN Considerations Copy Section

Resetting the Setup Token Copy Section

File: docs/advanced/scripts/modify-transfers.md Copy Chapter

Identify and Apply Transfers Historically

How To Copy Chapter

Explore Related Technologies & Topics

1. Project Overview & Quickstart (actualbudget/actual)

File: README.md

Getting Started

Key Links

Installation

Ready to Start Budgeting?

Are you new to budgeting or want to start fresh?

Are you migrating from other budgeting apps?

Documentation

Contributing

Code structure

Feature Requests

Translation

Repo Activity

Sponsors

File: packages/sync-server/src/app-gocardless/README.md

normalizeTransaction

File: packages/sync-server/README.md

Getting Started

Using the CLI tool

Documentation

Feature Requests

File: packages/desktop-client/README.md

E2E tests

Functional

Visual regression

File: packages/crdt/README.md

protobuf

Generating protobuf

File: packages/api/README.md

TypeScript

File: upcoming-release-notes/README.md

2. Official Technical Reference & Guides (actualbudget/docs)

File: README.md

Welcome

Installation Methods

Contributing

Issues

Pull Requests

Installing the Docs

Local Development

Build

Deployment

Writing Good Release Notes

File: docs/accounts/index.md

Off budget accounts

Adding a new account

Closing or deleting an account

Renaming an existing account

File: docs/accounts/reconciliation.md

Work Flow

Starting the Reconciliation Tool

Using the Reconciliation Tool for Off Budget Asset Tracking

File: docs/advanced/bank-sync/gocardless.md

Create SECRET and KEY for Actual

Link Accounts with GoCardless

Frequently Asked Questions

File: docs/advanced/bank-sync/simplefin.md

Generate Setup Token for Actual

Link Accounts with SimpleFIN

SimpleFIN Considerations

Resetting the Setup Token

File: docs/advanced/scripts/modify-transfers.md

How To