Creating a household budget using Actual

If you’re a household budgeter, like me, you’ve probably come across awesome apps and methods for budgeting that use the Envelope Method. One of the most well known of these is YNAB - it’s got a lot of features and does the job really well, but is very US-centric and costs a fair bit.

Fortunately there is a fantastic service called Actual and amongst the many reasons why it’s awesome is because:

  • it’s actively being developed
  • it’s free and open source
  • it runs locally on your machine
  • it can run as an Add-On to your Home Assistant

At time of writing, some downsides include that it has limited functionality in regards to bank-syncing (automatically importing transactions), or useful integrations with Home Assistant. (At the moment, none, apart from it can also run on your Home Assistant server.)

What is Envelope Budgeting
Envelope budgeting is a method where you take all the money you currently have (and later earn as income) and categorise it to how you want to spend it. Imagine you’ve got $1000 in your wallet, and you need to $300 of that for rent. You can take the $300 and put it in an envelope. Another envelope might have your food money. Another envelope might have your savings etc… When applied in budgeting software, it helps you understand how to budget for upcoming transactions & create a really useful household budget.

I only came across Actual a day or so ago. There are lots of ways to install Actual (remind you of something?) but fortunately it’s made extra simple for us as there is an HA add-on already available. Thank you @sztupy you legend.

Personally I have a Cloudflare Tunnel, so when I installed the add-on, I simply made sure the add-on was installed and didn’t worry about NGINX, or DuckDNS etc… I just updated my Cloudflare Tunnel dashboard and now I have a tunnel also pointing to localhost:5006, in addition the the one pointing to localhost:8123.

Lots of people envelope budget in different ways. I personally like to create broad categories called ‘Annual Expenses’, ‘Quarterly Expenses’, ‘Monthly Expenses’, ‘Weekly Expenses’, Other Expenses etc… And under annual, I’ll have a category for my home and car insurance, and under weekly I’ll have a category for my groceries etc…
I reckon, and this is cheating, if it’s new to you, to read some of the YNAB tutorials (many resources are available). The good news is it’s entirely up to you.

Very cool
One thing that I think is super cool about Actual, and this is better than YNAB, is an upcoming feature (currently Experimental) called ‘Goal Templates’.
When I use a simple syntax, I can have Actual figure out how much money I need to set aside:

Integrations with HA
I reckon the integrations with HA would be awesome. Imagine being able to budget for things like how much electricity you’ll be up for based upon how much energy you’ve drawn from the grid?

Hope this is helpful. I wrote this because although Actual has been around for a while, and although I’d done my best to find an alternative to YNAB, I had never stumbled upon it before. With luck, we’ll find a few eager fans here. Happy budgeting.


It seems really great! I wish I can check my budget about living.

Thanks for the this post, didn’t expect anyone would use my addon… But here it is! I found Actual while searching for YNAB alternatives, as I was still on the old desktop version and it started really showing its cracks trying to manage 10 years of budget data. Fortunately Actual was just what I needed - it could import from YNABv4, had basically the same feature set and could run fully locally as well if needed. Just wanted it to sync between my mobile and desktop and realized using my HA setup was just perfect for this. Not sure what other HA specific feature we could do to be honest, but I’m happy to have a look at making the integration better if there’s interest.


I’m using add on and it works fine, but wish we have integration from API. Then, we can check our budget with Assist.

Ah, good idea. Let me see if I can do something


Good day all, I am looking for instructions on how to set it up if I have nabucasa instead of duck DNS as shown in the instructions. Please help.

Thanks a lot for this add-on. Found it after hours of googling for options to replace YNAB. It has started to be a tad too expensive to reason with.
Installation was a bit difficult, but got easier once I started reading the instructions (like installing Maria and Ngingx) :smiley:
Migration from YNAB was quite painless. You can download the JSON format from YNAB web app, and upload to Actual Budget. Didn’t sign up for GoCardless yet, a bit concerned of the potential security risks.

One thing I still wonder is the internet accessibility. I have Home Assistant exposed to the internet, but with limited password attempts. I also have IDS/IPS on my router. Actual Budget has a bit too much functionality on the login page to my taste. You can run a demo for example. I wonder if there’s a chance that Actual Budget has a security flaw that could provide an attack vector to my whole Home Assistant…

Thanks for this addon, I just recently started using Actual but wanted a way to host locally. I use cloudflare for remote access, however am struggling to set up a tunnel to point to port 5006. Can anyone point me in the right direction please?

Edit: For anyone else reading I found the answer. You have to configure it in the cloudflare addon configuration tab. Place this in your additional hosts box:

-hostname: budget.yourdomain (or something similar)
service: http:// your home assistant ip address :5006

Save and restart cloudflare. Give it a few and then access budget.yourdomain and it should give you the landing page for actual with no sharedarray errors

@sztupy, I would be interested in contributing to the Home Assistant integration! I already checked a bit and it seems that the Actual app exposes the API through a Node.js client.

Given that Home Assistant runs Python, it would mean that packages like subprocess can be used to execute these js scripts from within the Python runtime. However, this would also mean that you would need to install npm and node on the host machine that runs Home Assistant, which might not be ideal.

Another option is to expand the addon or create an extra addon that includes an API ‘translator’ that exposes the Node.js API through RESTful endpoints. These endpoints can then easily be consulted within the Python runtime.

Let me know what you think and if/how I can contribute!