This post is a direct continuation of CrowdSec with Nginx Proxy Manager on Home Assistant OS: 8 Steps to Ultimate Homelab Security. If you haven’t set up CrowdSec yet — start there. Here we assume the addon is already running, the firewall bouncer is active, and Telegram notifications are in place.
Once CrowdSec is up and blocking threats, the next natural question is: how do I actually see what it’s doing? 🔍 The Telegram alerts notify you when something happens, but they don’t give you a living, real-time view of the current state. That’s exactly what a CrowdSec Home Assistant dashboard solves — a persistent panel inside HA showing every active ban, the scenario that triggered it, and how long it lasts.
In this guide we’ll set up the ha-crowdsec custom integration (v0.1.5), wire it to the CrowdSec Local API, and build a clean Lovelace card. The end result is a proper CrowdSec Home Assistant dashboard that lives right alongside your other automations and sensors.
🧩 What the Integration Actually Does
Before we dive into the setup, here’s what the CrowdSec Home Assistant dashboard integration actually exposes. The ha-crowdsec integration connects directly to the CrowdSec LAPI running inside the addon and exposes its data as native Home Assistant entities and events.
| Entity / Event | Description |
|---|---|
🛡️ sensor.crowdsec_active_decisions | Count of all currently active bans. Full decision list in attributes. |
⚡ crowdsec_new_decision | HA event fired in real time whenever a new IP gets banned. |
🔓 crowdsec_decision_removed | HA event fired when a ban expires or is manually removed. |
| ⚙️ UI config flow | No YAML needed. Configured entirely through Settings → Devices & Services. |
📦 Step 1 — Install via HACS Custom Repository
The first step to getting your CrowdSec Home Assistant dashboard working is installing the integration via HACS. It isn’t in the default store yet, so you need to add it as a custom repository — this takes about 30 seconds.
- Open HACS in the sidebar
- Click the three-dot menu ⋮ in the top-right corner
- Select Custom repositories
- In the URL field enter:
https://github.com/brott8/ha-crowdsec - Set Category to Integration and click Add
- Find CrowdSec LAPI in the list and click Download
- Restart Home Assistant after download completes
ℹ️ If you don’t have HACS installed yet, check the official HACS documentation. It’s a prerequisite for this guide.
🔑 Step 2 — Generate a Bouncer API Key
The integration authenticates to the LAPI using a bouncer API key. Open the CrowdSec addon terminal (or an SSH session to your HAOS host) and run:
# Create a new bouncer named homeassistant-dashboard cscli bouncers add homeassistant-dashboard
The command prints the API key once. Copy it immediately — it won’t be shown again.
⚠️ Your persistent config lives in
/config/.storage/crowdsec/config/— this is what survives addon restarts. The bouncer registration is handled by CrowdSec’s internal database, which is also persisted here, so your key will survive restarts.
🔍 Step 3 — Find the CrowdSec Addon IP Address
This is the most important step and the one that catches people off guard. When you try to use localhost in the integration setup, the CrowdSec Home Assistant dashboard connection fails — even though curl http://localhost:8080 works fine from your SSH terminal. 🤔
The reason: localhost inside the SSH session resolves to the HAOS host network, where the addon is reachable. But the HA core process runs in its own container with a separate network namespace — its localhost is different. The integration needs the actual container IP of the CrowdSec addon.
Run this in your SSH terminal to get it:
# Find the CrowdSec container IP in one command
docker inspect $(docker ps --format "{{.Names}}" | grep crowdsec) | grep '"IPAddress"'
You’ll see output like:
"IPAddress": "172.30.33.4",
Verify that it actually responds before moving on:
# Confirm the LAPI is reachable on that IP curl -s -H "X-Api-Key: YOUR_KEY_HERE" http://172.30.33.4:8080/v1/decisions
If it returns [] or a JSON array of decisions — you have the right address. ✅
⚙️ Step 4 — Configure the Integration
Now go to Settings → Devices & Services → + Add Integration and search for CrowdSec. This is where you connect the CrowdSec Home Assistant dashboard integration to your LAPI. Fill in the form using the IP you found above:
| Field | Value |
|---|---|
| Host | The IP from Step 3 (e.g. 172.30.33.4) |
| Port | 8080 |
| API Key | The key from Step 2 |
| Scheme | http |
| Scan Interval | 30 seconds |
Click Submit. If the LAPI is reachable with that key, the integration will create a sensor.crowdsec_active_decisions entity. Your CrowdSec Home Assistant dashboard is now live. 🎉
📊 Step 5 — Building the CrowdSec Home Assistant Dashboard Cards
With the sensor entity available, you can build the visible part of your CrowdSec Home Assistant dashboard. Open your dashboard in edit mode and add the following cards.
// Simple counter card
type: entity
entity: sensor.172_30_33_4_crowdsec_active_decisions
name: Active Bans
icon: mdi:shield-lock
// Full decisions table (Markdown card)
type: markdown
title: 🛡️ CrowdSec Active Decisions
content: |
| IP Address | Scenario | Duration |
|:---|:---|:---|
{% set decisions = state_attr('sensor.172_30_33_4_crowdsec_active_decisions', 'decisions') -%}
{% if decisions is iterable and decisions is not none and decisions | length > 0 %}
{%- for decision in decisions -%}
| `{{ decision.value }}` | {{ decision.scenario }} | {{ decision.duration }} |
{% endfor -%}
{%- else -%}
| ✅ No active bans | | |
{%- endif %}
✅ The table renders all currently active decisions from the sensor attributes. It automatically shows “No active bans” when the list is empty — no extra conditions needed.
🤖 Step 6 — HA Automations (Bonus Demo)
Beyond the visual CrowdSec Home Assistant dashboard, the integration fires native HA events that you can use in automations. A quick example — a persistent notification on every new ban:
alias: CrowdSec - Notify on New Ban
trigger:
- platform: event
event_type: crowdsec_new_decision
action:
- service: notify.persistent_notification
data:
title: "🚨 New IP Banned"
message: >
IP: {{ trigger.event.data.value }}
Reason: {{ trigger.event.data.scenario }}
Duration: {{ trigger.event.data.duration }}
📝 Note: If you followed the previous guide, you already have Telegram notifications set up at the CrowdSec level. This HA automation is shown purely as a demonstration of what the event system makes possible — you don’t need to duplicate notifications you already have.
✅ Summary
You now have a fully functional CrowdSec Home Assistant dashboard that shows active bans in real time, updates every 30 seconds, and fires native HA events you can hook into any automation. The hardest part of the whole setup is the container IP discovery in Step 3 — once you have that address, everything else clicks into place in minutes.
If you want to take security monitoring further, consider pairing this with a self-hosted Bitwarden instance behind Nginx Proxy Manager — with CrowdSec watching both, your homelab attack surface shrinks significantly. 🔒
Running everything on Proxmox? The whole stack — HAOS, CrowdSec addon, Nginx Proxy Manager — fits neatly inside a single VM, and the CrowdSec Home Assistant dashboard works identically in that setup. Check out the Proxmox VE 9.1 installation guide if you’re planning that route.
Leave a Reply