Setting Up Actual Budget

Written By Michael Montaque

Skill Level Disclaimer

his tutorial assumes you have a working knowledge of the terminal, experience with making CRUD API calls, and are comfortable using Git. Ideally, you should already have Home Assistant installed and be familiar with its basic operations. If you’re new to any of these topics, you may want to brush up on them before diving into this guide to ensure a smoother experience.

Affiliate Link Disclaimer

Some of the links on this page are affiliate links, which means I may earn a small commission if you click through and make a purchase at no additional cost to you. These commissions help support the content I create and keep it free for you. Thank you for your support!

What is Actual Budget?

“Actual Budget is a super fast and privacy-focused app for managing your finances.” I discovered this while trying to create a home assistant automation to monitor my finance similar to Rocket Money. This app can be hosted locally and gives you the ability to track your transaction against your budget.

Get Actual Budget Running

You have several options for installing the application. If you want to install it directly into Home Assistant, you can follow the instructions here. I did not go this route as it seemed way more complicated and I prefer to have a system like this decentralized from home assistant to reduce performance and security concerns. If you prefer a decentralized approach it is best to follow the docs provided by Actual. I will briefly walk through my personal setup below if you are interested in my approach.

My Installation approach

I am using a linux-based mini-pc (Click here if you want to see specs or purchase for yourself). On the device I create a folder to hold the application. In a terminal window I navigated to the folder and git cloned the repo 

~ git clone https://github.com/actualbudget/actual-server.git

You can either use yarn or npm to install the dependencies and run the project. The docs says to use yarn, but i couldn’t bother so and used npm. 

~ npm install
~ npm start

Click here to see the original instructions I followed. After running npm start this is the screen i get.

In order to use this application properly you will need to activate HTTPS. The docs provided by Actual have instructions to get it working. I strongly advise to use their docs. And to help reduce your friction, this is that path I took.

  • Use a self-signed certificate with mkcert

    • Since my linux machine was brand new, i needed to install certutil and then install homebrew for linux

    • with homebrew installed i was able to install mkcert

    • Then i was able to create the certificates with mkcert with mkcert install

  • Once you have the certificates you need to move them into the same folder as the project running Actual

  • Create a config.json with the path to the .key and .crt files

{
  "https": {
    "key": "/data/selfhost.key",
    "cert": "/data/selfhost.crt"
  }
}

  • Lastly stop the server (ctrl + C) and restart it (npm start)

You can access to the app using https in the url. For example if the IP of the computer with the server is 10.0.0.40 you can now reach it like this: https://10.0.0.40:5006 You should go to your URL and setup the app. It will ask you to create a password. Once inside the app i would suggest Adding an account

Create Proxy Server

Actual Budget has an API package that you can use to grab information from the server you have running. The API will only work on the same computer the server is running on which means you cannot use the API from any other computer. For example, I have the Actual server running on my mini-pc and Node-red is hosted in my NAS device. Node-Red lets me use the API’s directly but the calls would fail since it is executing on a different device.

  • On the same computer as the Actual Server create a sibling folder in the same directory as your Actual Budget server

  • In a terminal navigate inside that folder type npm init and fill out questions. When it asks about the main file, make sure it says index.js. (the other answers don’t really matter)

  • You should have a package.json file in the folder now. Install the following dependencies:

    • npm install @actual-app/api express sugar body-parser

      • @actual-app/api - This is the api that will access the Actual Server and return the data you need

      • express - Creates the API server that will serve as a proxy between the Actual budget server and any of the computers on the network that needs the information

      • sugar - This is a help file with useful functions for dates and other javascript objects

      • body-parser - This will let you recieve json data from post requests sent from client computers

  • Open your favorite text editor and create an index.js file. Copy and paste the data from this gist into your index.js file

  • You will need to replace the necessary info with yours

    • LINE 7 - Account Id can be found by going into the app, opening the developer console clicking your account (or refreshing the account page) and looking for the following network request.

    • LINE 65 - Replace the password with the one you used when setting up the app

    • LINE 69 - Sync Id can be found in the app under Settings → Show advanced settings → Sync ID

  • Back in the terminal start the application npm start

Testing the API

In your browser type in the ip of the computer with port 3000 and the endpoint of /getCurrentBudget (example: https://10.0.0.40:3000/getCurrentBudget)

You should see something similar to this dummy data below except yours may look a bit more empty.

Setup Actual AI

This will use AI to categorize your transaction. Your results will vary based on the model you use. You can check out the repo here. You can try it using docker however i simply pulled the repo down to my computer and ran it manually.

  • Create a folder in the same directory as the Actual Budget Server and Proxy Server.

  • In the terminal navigate into the newly created folder and pull down the project

    • git clone https://github.com/sakowicz/actual-ai.git

  • Create a .env file and fill out the following:

ACTUAL_SERVER_URL=http://actual_server:5006

ACTUAL_PASSWORD=your_actual_password

ACTUAL_BUDGET_ID=your_actual_budget_id

CLASSIFICATION_SCHEDULE_CRON=0 */4 * * * 

CLASSIFY_ON_STARTUP=true

SYNC_ACCOUNTS_BEFORE_CLASSIFY=false 

OPENAI_API_KEY=your_openai_api_key

OPENAI_BASE_URL=  ex: "http://ollama:11424/v1"

The OpenAI Base URL is optional and is used to point to your local llm. If you only want to use ChatGPT you can omit that line.

  • Run npm install and then npm start

Celebrate 🎉

If everything is working now you have a local budgeting app that is entirely hosted in your home! You can manually add transaction or you could like to try out the experimental feature SimpleFin. Since it is labelled as experimental, I will not cover the setup. Please refer to the doc and use your own discretion. However, I would like to share my experience with it.

SimpleFin Caveats

  1. I get emails almost daily from SimpleFin about how my access token is being used by another IP. My assumption is that since my mini-pc does not use a static IP address, it changes frequently which triggers a daily email from SimpleFin

  2. Syncs are about 1 day behind for me. If i make a purchase in Sept 3, and the charges are pending, they won’t show up in Actual Budget until the following day (or when they clear? I haven’t paid close enough attention)

  3. SimpleFin does cost money but it is relatively cheap in my opinion compared to other services. If you have a bank with API’s you can use, you can update the Proxy Server and create your own importer and call that instead of the bankSync method that is currently there.

One Last Thing

You technically have all the pieces to create automations around the data you collect in the actual budget app. Some improvements to the setup are:

  • Add the Proxy Server to a Docker for easier setup

  • Use proper certificates for better security

  • Enable the 3 servers to startup automatically if the computer reboots

Next i suggest creating home assistant sensors based on the data the gets returned. This will allow you to create dashboards and trigger automations based on your spending habits. Next week will be another tutorial explaining how to create custom sensors based on the data returned from this setup.

Michael Montaque
Previous

Trigger Smart Home Automations Without Siri or Apps? Here’s How!
Next

I made GPT clean my floors