Firewalla Local: Native, local, zero-latency Home Assistant control

[ccpk1 (Chad)]

Hi everyone,

I bought my Firewalla Gold a few years ago for the same reason many of you did: the promise of a powerful, prosumer, DIY-friendly firewall. To be fair, I like the Firewalla app—it does a great job of making complex networking accessible.

However, relying solely on it means the ecosystem is not only “Cloud-Locked,” but also “App-Locked.” Opening an app on your phone is perfectly fine for configuring a VLAN every once in a while. But it becomes a significant handicap when you want to dynamically orchestrate day-to-day routines. When you’re trying to automate a reliable internet cutoff for a 12 and 14-year-old at bedtime, or you want to leverage rich network data alongside the rest of your homelab services, the app-only approach falls short.

After years of maintaining custom SSH scripts to pull system metrics and wiring up clunky workarounds, I eventually reached a fork in the road: either reflash my hardware to a fully open-source OS, or finally build the native Home Assistant integration the community has been asking for.

I chose to build.

Today I’m releasing Firewalla Local (v1.0.0). It’s available via HACS and built from the ground up to meet Home Assistant’s “Platinum” quality standards with a 100% local data plane.

What it enables:

• Rule-Backed Switches: Expose your most-used rules (Internet Block, Social, Gaming, etc.) as simple switches with Optimistic UI—meaning your HA dashboard updates immediately with zero latency.
• Watched-User & Device Monitoring: Select specific household users or endpoints to track daily usage minutes, active apps, and connectivity, backed by the proven local payload.
• Timed Pauses: Use native pause_rule and resume_rule services in your automations (e.g., “Give the kids 30 more minutes of gaming”).
• Appliance Monitoring: Track system load, memory, disk usage, WAN IP details, and the latest successful Speed Test result natively in HA.

Security & Architecture:
This isn’t just a wrapper for a few scripts. It uses the official “Additional Pairing” protocol to securely retrieve the router’s local cryptographic bundle. After a one-time cloud-brokered pairing (identical to adding a second phone via the Firewalla app), all communication is 100% local, bypassing the cloud entirely. Note on Access: Because the integration communicates directly with the local hardware using this shared symmetric key, “unpairing” the device in your Firewalla app only removes the cloud association. To fully remove access, you simply delete the integration directly within Home Assistant to wipe the locally stored keys.

Hardware Testing:
I developed and actively run this on a Firewalla Gold. It should be fully compatible with the Purple, Gold Pro, and any other series running the Firewalla Box software that supports the local API. If you have one of those units, I’d love for you to install it and drop a note in the GitHub Discussions so I can update the supported hardware list.

Confirmed working models from user reports:

• Gold
• Gold Plus
• Purple

---

Support the Project

Building and maintaining local control integrations takes countless hours of development, testing, and covering hardware and tool costs. If Firewalla Local is giving you the network control you’ve been hoping for, here is how you can help keep the project alive:

Star this repository! (The Non-Negotiable)
If you install this integration and get value out of it, clicking the Star button at the top of the page is the easiest—and free—way to say thanks. It takes two seconds, helps others discover the project, and shows me that the community is actively using it.

Sponsor or Tip (The Ultimate Motivator)
While stars let me know the integration is alive, a sponsorship or tip is the absolute best way to affirm that the time and money spent building this tool is providing real value.

Financial support is never required, but it is the strongest motivation for me to keep fixing bugs, adding features, and maintaining this project long-term. If Firewalla Local makes your smart home better, consider showing your support!

---

Getting Started

Everything you need to install via HACS and configure the integration is documented in the User Guide:
Firewalla Local GitHub Repository
User Guide

Note: Check the User Guide in the repo for the pairing walkthrough, as you’ll need to extract the raw QR JSON from the Firewalla app to complete the initial setup.

I built this so we wouldn’t have to choose between great hardware and a local-first DIY experience. I’d love for you to try it out and let me know what you think!

[ccpk1 (Chad)]

Here is what is new in v1.1.0:

Presence and User Tracking

• Opt-in Device Trackers: You can now selectively opt-in eligible LAN clients to expose native device_tracker entities. Most commonly used with phones or other personal devices indicating if a person is home or away.
• Watched Users: Monitor specific household users with dedicated sensors reporting daily usage limits, unique device counts, per-app usage, and last_active status.

Host Management & Actions

You can now manage your network infrastructure directly from Home Assistant dashboards or automations:

• Wake-on-LAN: Wake compatible hosts via a native HA service call to the Firewalla.
• Host Admin: Rename hosts, toggle Notify when online/offline, and set or clear DHCP reservations with network-aware validation.
• Speed Tests: Trigger WAN internet speed tests natively from HA without opening the Firewalla app.

Data on Demand (13 New Services)

Instead of creating hundreds of useless sensors that bloat your HA database, I’ve exposed Firewalla’s deep metrics via 13 new Action Services. These services fetch rich local data on-demand and return it as dictionaries for your automations.

• Get Host Name Mappings (Perfect for syncing Firewalla names to custom DNS proxies like Control D or NextDNS)
• Get Network Segment Reports & Usage
• Get Time Usage Reports for monitored users.
• Get WAN Data Usage & Event Timelines
• Get Speed Test Results
• Plus the host admin services mentioned above (Wake, Set Name, Set DHCP, etc.)

Runtime Visibility & Debugging

For those building complex automations, visibility is key.

• Added a Sync Runtime diagnostic button to force an immediate local coordinator refresh.
• Added a runtime_data_updated_at attribute so your automations can verify data freshness.
• Enhanced the debug logging and pairing troubleshooting guidance for first-time setups.

---

How to Update

If you already have the repository added in HACS, simply check for updates and download v1.1.0.

If you are new to the project, everything you need to install via HACS and configure the integration is documented here:
Firewalla Local GitHub Repository
User Guide & Pairing Walkthrough

Support the Project

As always, building and maintaining local-first integrations takes a massive amount of time, testing, and coffee. If Firewalla Local is making your smart home better, please consider supporting the project!

Star the repository on GitHub! (Free & easy way to help the project grow)
Sponsor on GitHub or Buy Me A Coffee

Let me know how the new presence tracking and services are working for you!

[ccpk1 (Chad)]

---

Quick Reality Check: I need your feedback!

Hey everyone, I could use a quick favor and some feedback from anyone who has tried setting this up.

Right now, I only have a handful of stars on the repo, so I’m honestly flying a bit blind. I’ve had a few reports of the initial local pairing process failing, but because people usually only reach out when things break, I have no idea what the actual success rate looks like. I’m trying to figure out if these pairing failures are widespread, or if they are just edge cases isolated to specific Firewalla models or network configs.

If you are currently using this (or got it working):
Could you please take 30 seconds to reply with your Firewalla model? Also, if you had to do anything specific to get it to pair, please share! Knowing that it is working for people is really the only way I know if this project is worth continuing to dedicate development time to.

If you tried it and it failed to pair:
Please don’t give up silently! Head over to the GitHub repo and open an issue. I really want to get this sorted out, but I will likely need your help with a packet capture to see what your specific box is expecting. To make this as painless as possible, I’ve built a simple, single-command Windows script that automates the whole capture process and keeps your private keys totally safe on your machine.

Thanks in advance for the feedback—it really helps me know where things stand!

---

[Watanuki-kun]

Just got 1.1.4 working without issues by just using the user guide. I have a Firewalla Gold Plus.

[ccpk1 (Chad)]

Thank you for reporting it! Super helpful to know it’s working, at least for some.

So far we have confirmed working for:

• Gold
• Gold Plus

It would be great to hear from some others!

[aarick (Eric)]

Very cool. NIce work! Just got this setup today.

[ccpk1 (Chad)]

Great! What model do you have?

[eeeeeeeeeeeeean (ian)]

Very cool integration, Chad - I’m super excited to get this up and running on my home network. Have installed following instructions, but don’t see anything useful populated…? I’ve a Firewalla Gold Plus.

Set up the integration around 24 hours before screenshot (thought it might poll after a while). What am I missing?

[ccpk1 (Chad)]

What you are seeing is totally normal. The integration is built with an ‘opt-in’ model so it doesn’t instantly flood your Home Assistant with hundreds of firewall rules and devices.

By default, it only exposes a few basic entities like System Status (which holds a lot of good data in its attributes). For everything else—like specific rules you want to toggle—you just need to go into the integration’s Configure menu and select the exact items you want to bring in and control.

More detail about the different item types and configurations can be found in the User Guide.

[benzoid1 (Benzoid)]

This is a very cool integration, and excellent use of local access via the Additional Pairing.

As your warning in the README.md points out, I’m somewhat paranoid about expanding the attack surface for control of my firewall, so I have reluctantly not installed this integration. Not because I don’t trust you, but because I don’t trust anyone (also, I have a tablet that can control other Home Assistant things in the kitchen, and I wouldn’t want to put firewall control there!).

However, I was wondering if it would be relatively easy to produce a “Lite” version of this integration (or add an install-time option) that only provides read-only access to the Firewalla, i.e. make a lot of sensors with information about users present etc. I would be much happier about adding an integration that couldn’t change my firewall, and really all I want is information from the Firewalla anyway (since all the user device configuration is there).

Thanks again for your all-round excellent approach to making this integration!

[eeeeeeeeeeeeean (ian)]

Aaaaaahhhhh! Well guess who was too excited to install this to read ALL the documentation.

Thanks for the reply. And all the amazing work in building this integration.

[ccpk1 (Chad)]

@benzoid1

However, I was wondering if it would be relatively easy to produce a “Lite” version of this integration (or add an install-time option) that only provides read-only access to the Firewalla,

The way the pairing process works, it is emulating the app getting a full read / write key to your device. This is all reverse engineering, so there isn’t a way I know of or can try to replicate that provides anything less.

Of course the integration is only going to expose entities you choose and will only allow the administrators of ha to execute services, so your tablet wouldn’t directly allow access if setup correctly. That said, it is important to protect your ha as it does store a write key to your Firewalla even if the integration didn’t expose write services.

[benzoid1 (Benzoid)]

Ah, I’d been thinking a version (or installation if presented as an install-time option) of the integration with none of the “write” code in it would suffice, but I see there’d be a continued risk with the read-write key still present.
Thanks anyway – I still think this is the best/right approach for a Firewalla integration!

[ccpk1 (Chad)]

Tip: Don’t miss the hidden data in your Firewalla Local attributes!

I’ve gotten a few questions recently from folks asking if I plan to add sensors for things like CPU usage, specific app tracking, or speed test latency.

The good news is: that data is already there! To keep your Home Assistant instance from getting completely cluttered with hundreds of individual sensors, I designed the integration to pack as much related data as possible into the Attributes of the default entities.

If you click on your Firewalla entities and look at the details, you’ll find a lot of rich data. Here are a few examples of what is running under the hood:

1. System Status is more than just “Connected”
The System Status entity state might just say “Connected,” but if you look at the attributes, it acts as a full dashboard. It tracks your exact device counts (online vs. offline), live CPU and Memory usage, Disk usage by mount, and even your current WAN download/upload bytes.

2. User & Device Usage breaks down the details
If you look at a User Usage entity (like the “KADEN Usage” example in the screenshots), the main state shows the total internet time. But the attributes break that down further, showing you exactly which devices are associated with that profile, the last active time, and even an App usage by app breakdown (e.g., seeing exactly how much of that time was spent on YouTube, Instagram, etc).

3. Speed Test gives you the full diagnostic
The main state gives you your translated download speed, but the attributes hold your upload speed, latency, jitter, packet loss, and the specific ISP and server data from the test.

How to use this on your dashboards

If you want to pull any of this specific data out to display on a Mushroom card, an entity card, or use it in an automation, you can easily grab it using a template.

For example, to display the CPU Usage from the system status attribute, you would just use a template like this:

{{ state_attr('binary_sensor.firewalla_system_status', 'cpu_usage') }}

Or to pull a specific app’s usage time from a user profile:

{{ state_attr('sensor.firewalla_kaden_usage', 'app_usage_by_app').youtube | default(0) }}

Take a look through the attributes on your setup—you might find exactly what you’ve been looking to automate!

[aarick (Eric)]

Firewalla Purple

[benschumacher]

Hey. I just stumbled on this thread today and decided to try it out. I have it working with my Firewalla Gold SE. I haven't done much w/ it, yet, but wanted to let you know that it is working at a base level.

Cheers!

[ccpk1 (Chad)]

@benschumacher

I have it working with my Firewalla Gold SE. I haven't done much w/ it, yet, but wanted to let you know that it is working at a base level.

Great to hear! Drop a star on the repo when you get a chance to help others find it too!

[TomVT (Tom van Thiel)]

Well this looks damn promising. I have a Firewalla Gold Plus and I consider it one of the best private IT investments I ever made. I'm going to install your integration tonight and come back with my findings. And I will most certainly buy you some coffees.

[t2t]

Hello, I have the Firewalla gold plus. It seems my Firewalla has paired but hasn’t sync even after I press sync runtime. Anyway to see the data transferring?

[ccpk1 (Chad)]

@t2t

Anyway to see the data transferring?

Best way is probably look for one of the sensors or controls and change it from your Firewalla app. Once you make the change and sync, check the entity in the integration to look for a change.

If you aren’t seeing it, look at your home assistant logs for errors and you can also enable debug logging in the integration which will show a lot more detail about any processing and errors.

If you are seeing a lot of issues, I’d probably try removing the integration and adding again as a first step.