[Feature] Backup / Restore API #322

New Issue

GiteaMirror · 2026-02-28T18:58:58-06:00

GiteaMirror commented

2026-02-28 18:58:58 -06:00

Originally created by @aharbis on GitHub (Mar 28, 2023).

Verified feature request does not already exist?

I have searched and found no existing issue

💻

Would you like to implement this feature?

Pitch: what problem are you trying to solve?

I'm currently backing up my Actual file(s) manually via the web UI (Settings > Export Data), which appears to be the only method to do so.

Describe your ideal solution to this problem

In addition to automatic backups (https://github.com/actualbudget/actual-server/issues/173), it would be great if there was a way to create a backup programmatically via an API. Similarly, a restore API could be created (happy to split this into another issue if preferred).

Teaching and learning

The API Reference would need to be updated accordingly:

https://actualbudget.github.io/docs/Developers/API

Originally created by @aharbis on GitHub (Mar 28, 2023). ### Verified feature request does not already exist? - [X] I have searched and found no existing issue ### 💻 - [X] Would you like to implement this feature? ### Pitch: what problem are you trying to solve? I'm currently backing up my Actual file(s) manually via the web UI (Settings > Export Data), which appears to be the only method to do so. ### Describe your ideal solution to this problem In addition to automatic backups (https://github.com/actualbudget/actual-server/issues/173), it would be great if there was a way to create a backup programmatically via an API. Similarly, a restore API could be created (happy to split this into another issue if preferred). ### Teaching and learning The API Reference would need to be updated accordingly: https://actualbudget.github.io/docs/Developers/API

GiteaMirror added the feature needs votes labels 2026-02-28 18:58:58 -06:00

GiteaMirror closed this issue

2026-02-28 18:58:59 -06:00

GiteaMirror commented

2026-02-28 18:59:00 -06:00

@MatissJanis commented on GitHub (Mar 30, 2023):

Are you using actual-server? If so - you can set-up an automatic job to periodically copy over the database files. I haven't done it myself, but because all the database is stored in a file - I imagine it wouldn't be too difficult to pull off.

Would that solve your problem?

@MatissJanis commented on GitHub (Mar 30, 2023): Are you using `actual-server`? If so - you can set-up an automatic job to periodically copy over the database files. I haven't done it myself, but because all the database is stored in a file - I imagine it wouldn't be too difficult to pull off. Would that solve your problem?

GiteaMirror commented

2026-02-28 18:59:00 -06:00

@aharbis commented on GitHub (Mar 31, 2023):

Yes, I'm running actual-server in a Docker container. I've got /data mounted, so from the host machine I could backup that entire directory.

If I compare an export ZIP to what's in /data they definitely aren't 1:1, so it would be helpful to understand the mapping (is this documented?). The export has db.sqlite and metadata.json while /data shows:

data
├── config.json
├── selfhost.crt
├── selfhost.key
├── server-files
│   └── account.sqlite
└── user-files
    ├── file-1a047409-e371-4e6f-900e-3e12d19cf7c3.blob
    ├── file-395da899-14f3-4814-817e-4e44f2c22a04.blob
    ├── group-546bee81-eefa-4f11-835c-6a92f65f78bc.sqlite
    └── group-9a6431e4-c090-4d82-8b35-9c73d8b35147.sqlite

Above aside, I still think it would be beneficial to have a backup / restore API.

@aharbis commented on GitHub (Mar 31, 2023): Yes, I'm running `actual-server` in a Docker container. I've got `/data` mounted, so from the host machine I could backup that entire directory. If I compare an export ZIP to what's in `/data` they definitely aren't 1:1, so it would be helpful to understand the mapping (is this documented?). The export has `db.sqlite` and `metadata.json` while `/data` shows: ``` data ├── config.json ├── selfhost.crt ├── selfhost.key ├── server-files │ └── account.sqlite └── user-files ├── file-1a047409-e371-4e6f-900e-3e12d19cf7c3.blob ├── file-395da899-14f3-4814-817e-4e44f2c22a04.blob ├── group-546bee81-eefa-4f11-835c-6a92f65f78bc.sqlite └── group-9a6431e4-c090-4d82-8b35-9c73d8b35147.sqlite ``` Above aside, I still think it would be beneficial to have a backup / restore API.

GiteaMirror commented

2026-02-28 18:59:01 -06:00

@MatissJanis commented on GitHub (Mar 31, 2023):

Yeah, the export from the client will be more complete than actual-server. Though building an automated backup solution with it might be.. tricky. We're open to ideas though if you want to write a short RFC and/or implement it in a PR.

@MatissJanis commented on GitHub (Mar 31, 2023): Yeah, the export from the client will be more complete than `actual-server`. Though building an automated backup solution with it might be.. tricky. We're open to ideas though if you want to write a short RFC and/or implement it in a PR.

GiteaMirror commented

2026-02-28 18:59:01 -06:00

@rich-howell commented on GitHub (Apr 1, 2023):

Yeah, the export from the client will be more complete than actual-server. Though building an automated backup solution with it might be.. tricky. We're open to ideas though if you want to write a short RFC and/or implement it in a PR.

Just for clarification I think what you mean by "Complete" is that you will get the entire data directory, when we export data from the Application itself a lot of what is in that directory isn't required such as the certificates and the keys, exporting your data from the web application itself literally backups your budget it DOES NOT backup your server environment.

An automated method of being able to backup my budget would be amazing, sometimes I forget, having that on Actual Server somewhere that I could download would be great, maybe a page in settings with a list of available backups where I could click download or something like that but you could then set a n period to delete old backups so that the instance doesn't become snowed with backup files..

If the above was available I am not sure what the benefit of backing up the server itself would be? You could just bring an instance back online and then import the last downloaded budget.

@rich-howell commented on GitHub (Apr 1, 2023): > Yeah, the export from the client will be more complete than `actual-server`. Though building an automated backup solution with it might be.. tricky. We're open to ideas though if you want to write a short RFC and/or implement it in a PR. Just for clarification I think what you mean by "Complete" is that you will get the entire data directory, when we export data from the Application itself a lot of what is in that directory isn't required such as the certificates and the keys, exporting your data from the web application itself literally backups your budget it _**DOES NOT**_ backup your server environment. An automated method of being able to backup my budget would be amazing, sometimes I forget, having that on Actual Server somewhere that I could download would be great, maybe a page in settings with a list of available backups where I could click download or something like that but you could then set a n period to delete old backups so that the instance doesn't become snowed with backup files.. If the above was available I am not sure what the benefit of backing up the server itself would be? You could just bring an instance back online and then import the last downloaded budget.

GiteaMirror commented

2026-02-28 18:59:02 -06:00

@j-f1 commented on GitHub (Apr 1, 2023):

There's already functionality in the frontend for listing and loading backups. It only works on the Electron client since presently that’s the only one that saves backups but we could definitely add some similar functionality to the server and make the UI talk to that instead.

@j-f1 commented on GitHub (Apr 1, 2023): There's already functionality in the frontend for listing and loading backups. It only works on the Electron client since presently that’s the only one that saves backups but we could definitely add some similar functionality to the server and make the UI talk to that instead.

GiteaMirror commented

2026-02-28 18:59:02 -06:00

@github-actions[bot] commented on GitHub (May 1, 2023):

✨ Thanks for sharing your idea! ✨

This repository is now using lodash style issue management for enhancements. This means enhancement issues will now be closed instead of leaving them open. This doesn’t mean we don’t accept feature requests, though! We will consider implementing ones that receive many upvotes, and we welcome contributions for any feature requests marked as needing votes (just post a comment first so we can help you make a successful contribution).

The enhancement backlog can be found here: https://github.com/actualbudget/actual/issues?q=is%3Aissue+label%3A%22needs+votes%22+sort%3Areactions-%2B1-desc

Don’t forget to upvote the top comment with 👍!

@github-actions[bot] commented on GitHub (May 1, 2023): :sparkles: Thanks for sharing your idea! :sparkles: This repository is now using lodash style issue management for enhancements. This means enhancement issues will now be closed instead of leaving them open. This doesn’t mean we don’t accept feature requests, though! We will consider implementing ones that receive many upvotes, and we welcome contributions for any feature requests marked as needing votes (just post a comment first so we can help you make a successful contribution). The enhancement backlog can be found here: https://github.com/actualbudget/actual/issues?q=is%3Aissue+label%3A%22needs+votes%22+sort%3Areactions-%2B1-desc Don’t forget to upvote the top comment with 👍!

GiteaMirror commented

2026-02-28 18:59:03 -06:00

@MikesGlitch commented on GitHub (Aug 13, 2024):

Throwing my hat in here to say that I think we will always need the client side export because not everyone uses a server.

The way I'm seeing this is we'd have two features

Client side backup (optional) - could run on a schedule with the use of Persistent permissions file system access api
Server side backup (optional) - could run on a schedule
- An API endpoint could run the server side backup.

For the settings page:

We would need to update terminology to be clear. Instead of "Export" it should be called "Backup".
If it's a Server budget, the settings are: backup schedule and Server Directory
If Local budget, the settings are: backup schedule and local filesystem directory (which would be granted persistent permission, so the user isn't prompted while the backup runs)

Here's an example of persistent permissions in use with File System Access API - https://vscode.dev/

Those are just my thoughts, I haven't looked at the server code that much so I could be off.

@MikesGlitch commented on GitHub (Aug 13, 2024): Throwing my hat in here to say that I think we will always need the client side export because not everyone uses a server. The way I'm seeing this is we'd have two features - Client side backup (optional) - could run on a schedule with the use of [Persistent permissions file system access api](https://developer.chrome.com/blog/persistent-permissions-for-the-file-system-access-api ) - Server side backup (optional) - could run on a schedule - An API endpoint could run the server side backup. For the settings page: - We would need to update terminology to be clear. Instead of "Export" it should be called "Backup". - If it's a Server budget, the settings are: backup schedule and Server Directory - If Local budget, the settings are: backup schedule and local filesystem directory (which would be granted persistent permission, so the user isn't prompted while the backup runs) Here's an example of persistent permissions in use with File System Access API - https://vscode.dev/ Those are just my thoughts, I haven't looked at the server code that much so I could be off.

GiteaMirror commented

2026-02-28 18:59:03 -06:00

@masoncfrancis commented on GitHub (Feb 17, 2025):

Did anything ever happen with this? I'm interested in doing server backups, specifically, without having to use the client UI every time. I'd love to be able to automate backups of the server

@masoncfrancis commented on GitHub (Feb 17, 2025): Did anything ever happen with this? I'm interested in doing server backups, specifically, without having to use the client UI every time. I'd love to be able to automate backups of the server

GiteaMirror commented

2026-02-28 18:59:04 -06:00

@MikesGlitch commented on GitHub (Feb 17, 2025):

Did anything ever happen with this? I'm interested in doing server backups, specifically, without having to use the client UI every time. I'd love to be able to automate backups of the server

You can automate it with the API and a scheduler: https://actualbudget.org/docs/api/#connecting-to-a-remote-server

We don't currently have anything baked into Actual.

@MikesGlitch commented on GitHub (Feb 17, 2025): > Did anything ever happen with this? I'm interested in doing server backups, specifically, without having to use the client UI every time. I'd love to be able to automate backups of the server You can automate it with the API and a scheduler: https://actualbudget.org/docs/api/#connecting-to-a-remote-server We don't currently have anything baked into Actual.

GiteaMirror commented

2026-02-28 18:59:04 -06:00

@Jonas-Sander commented on GitHub (Mar 31, 2025):

Being able to run actual export ./my-export.zip or something similar would be awesome.

Is the data being downloaded from await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f'); the same as exporting the backup via the web-interface? (.zip file with all data)?

@Jonas-Sander commented on GitHub (Mar 31, 2025): Being able to run `actual export ./my-export.zip` or something similar would be awesome. Is the data being downloaded from `await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f');` the same as exporting the backup via the web-interface? (`.zip` file with all data)?

GiteaMirror commented

2026-02-28 18:59:05 -06:00

@Jonas-Sander commented on GitHub (Apr 8, 2025):

Did anything ever happen with this? I'm interested in doing server backups, specifically, without having to use the client UI every time. I'd love to be able to automate backups of the server

You can automate it with the API and a scheduler: https://actualbudget.org/docs/api/#connecting-to-a-remote-server

We don't currently have anything baked into Actual.

@MikesGlitch
I tried to make a backup using this method, but I get the following error when trying to import the data: Database is out of sync with migrations

I used the await api.downloadBudget(syncId); method like u said and then zipped the results.
See the code here: https://github.com/Jonas-Sander/actual-backup

@Jonas-Sander commented on GitHub (Apr 8, 2025): > > Did anything ever happen with this? I'm interested in doing server backups, specifically, without having to use the client UI every time. I'd love to be able to automate backups of the server > > You can automate it with the API and a scheduler: https://actualbudget.org/docs/api/#connecting-to-a-remote-server > > We don't currently have anything baked into Actual. @MikesGlitch I tried to make a backup using this method, but I get the following error when trying to import the data: **Database is out of sync with migrations** ![Image](https://github.com/user-attachments/assets/38f7b78d-52a2-4bb2-ba33-e3a4a92f2c82) I used the `await api.downloadBudget(syncId);` method like u said and then zipped the results. See the code here: https://github.com/Jonas-Sander/actual-backup

GiteaMirror commented

2026-02-28 18:59:05 -06:00

@Jonas-Sander commented on GitHub (Apr 8, 2025):

Ah, nevermind, I used a newer version of the api than was running on my instance. Sorry for the ping!

@Jonas-Sander commented on GitHub (Apr 8, 2025): Ah, nevermind, I used a newer version of the api than was running on my instance. Sorry for the ping!

GiteaMirror commented

2026-02-28 18:59:06 -06:00

@thromer commented on GitHub (Sep 19, 2025):

As a first step, would it make sense to expose the existing importBudget and exportBudget functions in budgetfiles/app.ts via the API?

@thromer commented on GitHub (Sep 19, 2025): As a first step, would it make sense to expose the existing [`importBudget`](https://github.com/actualbudget/actual/blob/e30a38ced8d1509e34ac2a85170fa7ec218eaea2/packages/loot-core/src/server/budgetfiles/app.ts#L459) and `exportBudget` functions in [`budgetfiles/app.ts`](https://github.com/actualbudget/actual/blob/master/packages/loot-core/src/server/budgetfiles/app.ts) via the API?

Sign in to join this conversation.

Branches Tags

master

claude/browser-compatible-api-QbhHh

matiss/theme-catalog-responsive-layout

claude/improve-cli-transactions-waTUY

matiss/remove-browser-connection-extension

claude/publish-react-native-ios-j8qoT

js-proxy

claude/fix-flaky-ci-job-5gDdz

react-query-rules

react-query-useSchedules

claude/nightly-theme-validation-scan-DzOGD

claude/debug-simplefin-error-ZuKzB

matiss/desktop-client-subpath-imports

claude/fix-simplefin-ssrf-T31gX

claude/release-notes-validation-X7rvR

add-claude-github-actions-1772738270730

cursor/sync-performance-notification-9899

react-query-prefs

matiss/chunked-sync-and-progress-ux

v26.2.1

copilot/sub-pr-6880

fix-react-query-clear-on-close-budget

copilot/sub-pr-6140

feat/auto-note

feat/scoped-bank-sync

cursor/desktop-transactions-react-table-1d0c

fix-exhaustive-deps-App

copilot/fix-find-replace-bug

release/v26.2.0-pre

matiss/browser-tests

mobile-fix-drag-and-drop-across-groups

budget-table-v2

PayeeAutocomplete2

pglite

bugfix/plugins/fix-plugins-sw

feat/plugins/plugins-core-package

prerelease

matiss/unicode-minus-fix

cursor/fix-actual-github-issue-6206-gemini-3-pro-preview-9c37

TransactionFormPage

cursor/implement-mortgage-and-loan-account-type-78ca

tests-update-fill-with-pressSequentially

mobile/link-modal

deps/25.11

cursor/fix-update-vrt-apply-ci-job-dispatch-b324

sync-server-plugins

cursor/propose-patch-for-github-issue-5680-2a18

fix/compiler-preserve-inner-dollar-escapes

cursor/analyze-actual-budget-issue-and-propose-fix-5b70

coderabbitai/docstrings/0c070e5

cursor/add-wip-prefix-and-comment-to-prs-d78d

jfdoming/08-21-auto-focus-on-navigate-in-all-browsers

show-totals-on-mobile-budget-banners

allow-child-transactions-make-transfer

mobile-calculator-keyboard

payee-geolocation

enhance/restore_scroll_position

dm-fix-second-click-on-mobile-new-transaction-2

scrollToLocationBudget

alert-autofix-38

tsconfig-composite

mobile-fix-uncategorized-transactions-on-tracking-budgets

server-budget-handlers

fix-sql-injection-in-cleanup-template

non-chrome-draggable-workaround

mobile-budget-page-swipe-navigation

ts-db-all

stable

dark-theme-with-brand-colors

fix-mobile-delete-group

ts-db-select

UnderKoen/reconcile-context-menu

master-before-server-merge

v25.2.1

ts-runQuery

rename-redux-hooks

UnderKoen/3557-persist-state-in-history

remove-redux-CLOSE_BUDGET

fix-exhaustive-deps-errors-FinancesApp

redux-toolkit-createSlice-backup

accounts-function-component

ts-useSplitsExpanded

loot-core-server-package

useTransactios-in-TransactionEdit

react-aria-input

move-redux-to-desktop-client

QueryState-type

fix-themes-applied-late

mobile-vrts

revert-3295-spendingCardFix

react-aria-button-4

split-payee-on-mobile

twk3/pin-apis-crdt

notes-tag-autocomplete

ts-LoadBackup

dnd-kit

package-upgrades

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/actual#322