What is Actual Budget?

Actual Budget is a super fast and privacy-focused app for managing your finances. At its heart is the well-proven and much-loved Envelope Budgeting methodology.

👉 Learn more about Actual Budget

How to Set Up

Prerequisites

Before you begin, make sure you have:

• ✅ An Actual Budget instance (self-hosted or using a hosting provider)

• ✅ At least one bank connected in Lunch Flow

• ✅ Node.js installed on your machine (for running the sync script)

Note: Currently, Actual Budget integration requires running a sync script (actual-flow) on your machine. A simpler direct API integration is coming soon.

Setup Steps

1. Get your Lunch Flow API token

1. Log in to Lunch Flow

2. Go to the Destinations page

3. Click "Add Destination"

4. Select "API"

5. Your API token will be displayed,copy it and save it securely

2. Get your Actual Budget connection details

You'll need:

• Your Actual Budget server URL (e.g., https://actual.yourdomain.com)

• Your Actual Budget password (from your instance settings)

• Your Sync ID (visible in Actual Budget → Settings → Show advanced settings → Sync ID)

3. Install and run actual-flow

Run the one-click install command:

npx @lunchflow/actual-flow 

The script will walk you through the setup, prompting you for:

• Your Lunch Flow API token

• Your Actual Budget server URL

• Your Actual Budget password

• Your Actual Budget Sync ID

After configuration, the script will automatically sync your transactions.

(Optional) Set up automatic syncing

To sync automatically on a schedule, set up a cron job or scheduled task to run npx @lunchflow/actual-flow daily.

🔒 Security & Privacy

Your Lunch Flow API token grants access to your transaction data. Keep it secure and never share it publicly.

👉 Learn more about our Security & Privacy — encryption, compliance, and data protection.

FAQ

How often does data sync?

The sync happens whenever you run the actual-flow script. You can set up a cron job or scheduled task to run it automatically (e.g., daily).

Can I sync to an existing Actual Budget account?

Yes! The actual-flow script will match your Lunch Flow accounts to existing accounts in Actual Budget based on account names. To avoid duplicate transactions, the script tracks which transactions have already been imported.

Does this work with self-hosted Actual Budget?

Absolutely! Actual Budget is designed to be self-hosted, and actual-flow works perfectly with your own instance.

When will the direct API integration be available?

We're waiting for the Actual Budget team to complete some plugin work on their side. Once that's done, you'll be able to connect directly through Lunch Flow without running a separate script. Upvote this feature request to be notified!

What if I don't want to run a script on my machine?

For now, the script is required to sync with Actual Budget. Alternatively, you can use CSV/OFX export and manually import into Actual Budget until the direct API integration is available.

I'm getting errors with @actual-app\api in the traceback, like "No budget file is open"

If you're seeing errors related to @actual-app\api (like "No budget file is open" or other Actual Budget-specific errors), please ask for help in the #support channel in Actual Budget's Discord server. The Actual Budget team is in the best position to help debug issues with their API and budget files.