Skip to main content

​
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

  • 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)
Currently, Actual Budget integration requires running a sync script (actual-flow) on your machine. A simpler direct API integration is coming soon - upvote here to be notified when it’s available!

​
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:
  1. Note your Actual Budget server URL (e.g., https://actual.yourdomain.com)
  2. Get your Actual Budget password from your instance settings
  3. Note your Sync ID (visible in Actual Budget → Settings → Show advanced settings → Sync ID)
3
Install and run actual-flow:
  1. Run the one-click install command:
    npx @lunchflow/actual-flow
  2. 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
  3. After configuration, the script will automatically sync your transactions
  4. (Optional) Set up a cron job or scheduled task to run npx @lunchflow/actual-flow daily for automatic syncing

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

​
Need Help?