CrowdSec Web UI: A Self-Hosted Dashboard for CrowdSec Alerts, Decisions and Metrics

The gap between cscli and a browser tab

CrowdSec ships a command line tool, cscli, and a Local API. Both are sufficient for automation. Neither is pleasant when you want to answer a question like which autonomous systems have been hitting this host this week, or which decisions are still active across two CrowdSec installations. The repository describes the project as a dashboard for CrowdSec covering alert investigation, decision management, runtime metrics and notifications. That is the scope. It is a read-and-write front end over the LAPI, aimed at the person who runs CrowdSec on a home server or a small fleet of VPS instances and wants the alert history to be browsable rather than greppable. The README's feature table lists searchable alert history, CrowdSec alert contexts, IP, AS and location details, simulation labels, configurable columns, manual bans with custom durations and reasons, and cleanup actions. Those are all operations cscli already exposes, rearranged for a pointer. The audience is therefore narrow and specific: existing CrowdSec operators, not people evaluating CrowdSec itself.

How the dashboard talks to the Local API

The Web UI is a client of the CrowdSec LAPI, and it authenticates the same way a CrowdSec agent or bouncer does. The README gives two paths. The first is watcher password authentication: you generate a secret, register a machine named crowdsec-web-ui with cscli machines add, and hand the resulting username and password to the container through environment variables. The second is agent mTLS, which the README delegates entirely to the CrowdSec TLS authentication guide rather than restating. There is no separate database of alerts. The dashboard queries the LAPI and renders what comes back, which is why the README insists you need a running CrowdSec LAPI before anything else. The one piece of state the container owns is the directory mounted at /app/data, which holds whatever the UI persists locally: the initial administrator account, notification rules, and the quick filters the README describes as persistent and count-aware. That split matters operationally, because backing up the LAPI does not back up your dashboard configuration, and vice versa.

Registering the machine without clobbering credentials

The registration step has a detail that is easy to miss and destructive if you miss it. The README's command is docker exec crowdsec cscli machines add crowdsec-web-ui --password 'replace-with-generated-password' -f /dev/null, with a local variant using sudo cscli. The -f /dev/null flag is called out in an important note: it registers the machine without overwriting the CrowdSec container's existing credentials file. Drop that flag and you are writing over credentials that other components on the same LAPI may be using. The password itself is generated with openssl rand -hex 32, and the README tells you to substitute the printed value in both the cscli command and the container environment. This is the kind of sequence where a copy-paste error produces a dashboard that starts, connects to nothing, and gives you no obvious clue why. Register the machine first, then start the container.

Docker Compose configuration keys that matter

The README includes a Compose fragment and notes that a ready-to-use docker-compose.yml ships in the repository. The service is ghcr.io/theduffman85/crowdsec-web-ui:latest, the container name is crowdsec_web_ui, and port 3000 is published. Three environment variables carry the connection: CONFIG_INSTANCE_LAPI_URL, CONFIG_INSTANCE_LAPI_AUTH_USERNAME and CONFIG_INSTANCE_LAPI_AUTH_PASSWORD. The prefix CONFIG_INSTANCE_ is worth reading literally. It implies a per-instance namespace, which lines up with the multi-instance feature: several CrowdSec LAPIs, per-instance views, and a Combined scope for Dashboard, Alerts and Decisions. The README does not spell out how a second instance is declared, so if you run more than one LAPI, confirm the numbering or naming convention from the repository's own compose file rather than guessing from this fragment. The example also shows the local-instance case, where CONFIG_INSTANCE_LAPI_URL becomes http://host.docker.internal:8080 and an extra_hosts entry mapping host.docker.internal to host-gateway is uncommented. Start with docker compose up -d, then open http://localhost:3000 and create the initial administrator account.

Authentication choices and the read-only switch

The security row in the feature table is longer than most dashboards of this size bother with: initial administrator setup, password and TOTP login, passkeys, OIDC SSO, group roles, and an instance-wide read-only mode. The read-only mode is the interesting one. A dashboard that can create manual bans and run cleanup actions is a privileged interface, and pointing it at a production LAPI gives anyone who reaches port 3000 the ability to change blocking decisions. Read-only mode is the mitigation the project offers, and group roles let you separate the people who look from the people who act. The README does not describe how roles map to specific actions, so treat the role model as something to inspect in the UI before you hand out accounts. Passkeys and OIDC SSO are both listed, which suggests the project expects to sit behind an existing identity provider in some deployments, though the README gives no configuration example for either.

Notifications, metrics and what they depend on

Two features deserve separate scrutiny because they have external dependencies. Notifications cover alert, decision, CVE, availability and update rules, delivered through Email, Gotify, MQTT, ntfy or Webhooks. That is a rule engine with five transports, and it lives inside the dashboard rather than inside CrowdSec, so your notification history and rule definitions are part of the /app/data volume. Metrics are described as optional Prometheus views covering LAPI activity, bouncers, AppSec, parsers, latency, parsing time and whitelists. Optional is the operative word: these views presumably need Prometheus instrumentation on the CrowdSec side, and the README does not explain what to enable. If you are not already scraping CrowdSec with Prometheus, expect this section of the UI to be empty or unhelpful, and check the repository for the prerequisite before assuming the metrics tab is broken.

Where this is the wrong tool

The dashboard is a view over one or more CrowdSec LAPIs. It is not a SIEM, and it does not correlate CrowdSec events with anything else. If your actual requirement is a single interface across CrowdSec, Suricata, firewall logs and cloud audit trails, this project does not attempt that, and the multi-instance feature will not get you there because every instance it knows about is a CrowdSec LAPI. A second limitation is reachability. The container needs network access to the LAPI, and the README's local-instance example exists precisely because that is not automatic when CrowdSec runs on the host and the UI runs in a container. A third is that the project is a single-maintainer repository under AGPL-3.0. If your organisation has policies about copyleft licences in the tooling layer, or about depending on software with one primary author, those are real considerations and the README does not address either. The release cadence visible in the supplied material shows three releases in August 2026, with the most recent push in early September 2026, so the project is active, but activity is not the same as a support contract.

Alternatives and the difference in approach

The most direct alternative is not another dashboard but the tools CrowdSec already provides. cscli covers alert listing, decision creation and deletion, and metrics inspection from a terminal, and it is the interface CrowdSec documents and supports. The difference is interaction model rather than capability: cscli is composable and scriptable, so it fits cron jobs, configuration management and audit trails, while crowdsec-web-ui is a persistent stateful service that a human clicks through. If your workflow is already automated, adding a dashboard adds a component to patch and a volume to back up without removing any cscli usage. Grafana is the other realistic alternative, and the comparison is sharper. Grafana reads from a time-series database, so it answers trend questions well and gives you alerting across many data sources, but it does not write decisions back to a LAPI. crowdsec-web-ui does write, which is exactly why it needs authentication, roles and a read-only mode. Pick based on whether you need to act on alerts or only observe them.

Maintenance cost and licence terms to check

Running this means maintaining a Node and Docker container alongside CrowdSec, keeping the image updated, and backing up /app/data. The repository publishes a container to ghcr.io, and the README links a Trivy scan workflow, so image vulnerabilities are at least being checked upstream. Upgrades are the part to think about before you commit: the README does not describe a migration path for the local data directory, so a version bump that changes the stored schema could require care, and the supplied material does not confirm whether one exists. On licensing, the project is AGPL-3.0. That is a copyleft licence with a network-use clause, which matters if you modify the source and expose the modified version to users over a network. This article is not legal advice; if your organisation has an open source policy, route the AGPL-3.0 terms through it before deploying rather than after.

Editorial conclusion

Adopt crowdsec-web-ui if you already run CrowdSec and want a browser interface for alerts, decisions and notification rules without building one, and if you are comfortable with AGPL-3.0 terms and a container that must be given LAPI credentials. Do not adopt it if you need a single pane of glass over several security products, if you cannot expose or reach a LAPI, or if you expect it to replace cscli for scripted work. Before deploying, verify three things: that your LAPI answers on the URL you put in CONFIG_INSTANCE_LAPI_URL, that the machine you registered with cscli machines add can read alerts and decisions at the scope you need, and that the /app/data volume is writable and backed up, because the dashboard's own state lives there and not in CrowdSec.

Official sources

1. Issues
2. License: AGPL-3.0
3. README
4. Releases
5. TheDuffman85/crowdsec-web-ui on GitHub