CrowdSec Manager: a web and mobile dashboard for a CrowdSec stack

A dashboard that manages the stack rather than replacing it

CrowdSec Manager is described as a web-based management interface for CrowdSec, covering decisions, alerts, allowlists, scenarios, hub, logs, backups and Traefik integration. The project description adds the multi proxy angle, naming Caddy and NPM, and says the project replaces the bash script with a modern, user friendly ShadcnUI built with Go and React.

That last phrase is the honest description of the whole thing. The starting point was a shell script that managed a CrowdSec deployment, and this is a UI over the same operations, with the script's job done properly in a language where an interface is possible. The README badge marks the status as stable, and the version scheme has reached 2.4.1.

The distinction between managing the stack and doing detection matters for expectations. CrowdSec Manager does not decide which IPs are malicious, it shows you what CrowdSec decided and lets you act on it: write allowlists, look at alerts, inspect the hub items you have installed, read the logs, arrange backups, and change scenario and collection configuration. The detection is CrowdSec's job and stays CrowdSec's job.

The scope of the features is listed in a single line at the top of the README, and it maps cleanly onto the operations an operator actually performs. Decisions and alerts are the read side. Allowlists, scenarios and the hub are the write side. Logs and backups are the maintenance side, and Traefik integration is the part that makes the stack reachable.

The mobile client is a separate piece of the project rather than a responsive afterthought, and the README describes it as a native iOS and Android app supporting two connection modes, Pangolin for token-based remote access and Basis for direct URL. The mobile directory at the repository root and the android-application, ios-app and crowdsec-mobile tags confirm that it is a first-class target rather than an experiment.

Two images, and the choice between the full stack and CrowdSec alone

The release section documents two Docker images, and the difference between them is the most important configuration decision a user makes.

The Pangolin image, `hhftechnology/crowdsec-manager:latest`, is the full stack with Traefik, Pangolin and Gerbil. The independent image, `hhftechnology/crowdsec-manager:independent`, is CrowdSec only with no Traefik. The image size for linux/amd64 is given as 44MB.

The quick start for the independent setup begins with creating the directories the app expects:

mkdir -p ./config/crowdsec ./logs/app ./data

and then the compose file wires the two services together:

services:
  crowdsec-manager:
    image: hhftechnology/crowdsec-manager:independent
    container_name: crowdsec-manager
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - ENVIRONMENT=production
      - CONFIG_DIR=/app/config
      - DATABASE_PATH=/app/data/settings.db
      - INCLUDE_CROWDSEC=true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./config:/app/config
      - ./logs/app:/app/logs
      - ./data:/app/data
    networks:
      - crowdsec-network
    depends_on:
      - crowdsec

  crowdsec:
    image: crowdsecurity/crowdsec:latest
    container_name: crowdsec
    environment:
      - COLLECTIONS=crowdsecurity/linux
    volumes:
      - ./config/crowdsec/acquis.yaml:/etc/crowdsec/acquis.yaml:ro
      - crowdsec-db:/var/lib/crowdsec/data/
      - crowdsec-config:/etc/crowdsec/
    networks:
      - crowdsec-network

networks:
  crowdsec-network:
    driver: bridge

volumes:
  crowdsec-db:
  crowdsec-config:

And then the two commands that start it and check it:

docker compose up -d
curl http://localhost:8080/api/health/stack

That health endpoint is the thing to put in a monitoring check, and the stack health path naming tells you it reports on the whole stack rather than just the web process.

The environment variables in the compose file are the configuration surface, and they are worth reading as a map of what the tool can reach. `CONFIG_DIR` and `DATABASE_PATH` say where its own configuration and its SQLite settings database live. `INCLUDE_CROWDSEC=true` switches on the CrowdSec integration. `CROWDSEC_METRICS_URL` in the Pangolin variant points at the metrics endpoint on port 6060. `ALERT_LIST_LIMIT=5000` bounds how many alerts the dashboard holds, which is a real operational setting for a busy node.

In the full compose file there are more still: `TRAEFIK_DYNAMIC_CONFIG`, `TRAEFIK_STATIC_CONFIG`, `TRAEFIK_ACCESS_LOG` and `TRAEFIK_ERROR_LOG` give the tool read access to Traefik's configuration and logs, `CROWDSEC_ACQUIS_FILE` points at the acquisition file, `BACKUP_DIR` with `RETENTION_DAYS=60` configures the backup schedule, and `COMPOSE_FILE`, `DOCKER_HOST` and `PANGOLIN_DIR` cover the management of the compose stack itself.

The Docker socket is the widest permission in the whole setup

Every compose example in the README mounts the Docker socket into the manager container, and it is worth being blunt about what that grants.

The mount is `/var/run/docker.sock:/var/run/docker.sock`, and it appears in the Pangolin example, in the independent example and in the repository's own docker-compose.yml. The Go dependencies confirm the intent: `github.com/docker/docker` is a direct dependency, along with `github.com/compose-spec/compose-go/v2` for reading a compose file and `github.com/robfig/cron/v3` for scheduling.

With the socket mounted, the manager can do whatever the Docker API allows, which in practice means it can start, stop, recreate and inspect containers on the host. The README also shows it mounting the compose file itself, `/root/docker-compose.yml:/app/docker-compose.yml`, and the Pangolin configuration directory, which is how a tool ends up able to reconfigure and redeploy the stack it is monitoring.

The upside is real. A dashboard that can show you a decision and then also restart the CrowdSec container that made it is a genuinely different tool from one that only reads. The container controls screen in the mobile app listing is part of that story, as is the terminal shell screen.

The cost is that the socket is effectively root on the host, and a web application reachable over a network holding it is a serious thing to expose. The mitigations visible in the project are the network topology, the `traefik.enable` label with a host rule of `manager.localhost` routing through the web entrypoint, and the Traefik integration itself, which is a reverse proxy in front of the manager. The licence is listed as MIT in the README badge, and the last push was on 2026-07-02 with releases 2.4.1 and 2.4.0 from May 2026.

The repository carries Kubernetes charts and a separate mobile tree

The top level listing of the repository shows how much more than a web dashboard this is.

There is `web/` for the front end and `cmd/`, `internal/` and `pkg/` for the Go backend, with `pkg/contracts/` holding the API contract types and their generator. The `mobile/` directory is the native client, kept separate from the web application rather than sharing its code.

Then the deployment surface. There is `charts/` for Helm charts, `k8s/` for Kubernetes manifests, `configs/` for configuration, `data/` and `scripts/` for runtime and build helpers, `docs/` for documentation, and a `docker-entrypoint.sh` at the root. Two documentation files sit at the top with names that describe their scope precisely, `USAGE.md` and `VOLUMES_AND_PATHS.md`.

The split between USAGE.md and VOLUMES_AND_PATHS.md is the useful part. The compose examples are full of volume mounts, and the path mapping from the host into the container is where a deployment of this kind actually goes wrong, so a file dedicated to it is a sign the author has debugged that. The Pangolin example mounts a config folder, a compose file, a backups directory, a data directory and an optional GeoIP database, and each of those has to point at the right place on the host.

The compose variants in the repository root tell the same story from the other side. There is `docker-compose.yml` for the full stack with the Traefik labels and the `manager.localhost` host rule, `docker-compose.pangolin.yml` for the Pangolin arrangement, and `docker-compose.dev.yml` for development, alongside a `Dockerfile` and a `Dockerfile.dev`.

The Go module path is simply `crowdsec-manager`, and the go directive is 1.23.0, matching the golang:1.23-alpine builder image in the Dockerfile. The gin version in the dependencies, 1.10.0, is a reasonably current one, and the Docker client pin is a development snapshot rather than a release tag, which is the kind of detail worth knowing if you rebuild the image yourself and the build starts failing after a docker client change.

A three stage image with a C Go backend and a Shadcn front end

The Dockerfile tells you the shape of the application, and it is a three stage build in the standard Next.js standalone arrangement.

The first stage builds the front end on node:20-alpine, copying the web package files, installing with `npm ci --legacy-peer-deps`, and running the build. The second builds the Go backend on golang:1.23-alpine, and the comment there is explicit that CGO is required for go-sqlite3, so it installs git, gcc, musl-dev and sqlite-dev before building with `CGO_ENABLED=1 GOOS=linux`.

The final stage is a plain alpine image with ca-certificates, tzdata and curl added, the binary and the built front end copied in, and a health check that curls the health endpoint on the port from the environment:

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:${PORT:-8080}/health || exit 1

One detail in the Dockerfile deserves attention because it is easy to miss. The comment says to run as root user, with no USER directive, and explains that this allows write access to mounted volumes. That is a deliberate choice rather than an oversight, and it is the kind of decision that should be in your threat model if you run this on a host with anything else on it.

The same file documents the optional GeoIP database. The image creates `/app/geoip` as the default mount point for an optional GeoLite2-City.mmdb, with `GEOIP_DB_PATH` to override, and the behaviour when the file is absent is stated plainly: the dashboard endpoints still respond, and country and coordinates are simply omitted. So the location enrichment in the dashboards degrades rather than fails, which is the right default for an optional dataset.

The Go dependencies describe the features. Gin for the HTTP API with CORS and gzip middleware, `gorilla/websocket` for the live log and alert streams, `mattn/go-sqlite3` for the settings database, `oschwald/geoip2-golang` for the location lookup, `buger/jsonparser` for fast JSON parsing, `nats-io/nats.go` for messaging, `robfig/cron/v3` for the backup and retention schedule, `zap` for logging and `gopkg.in/yaml.v3` for configuration. The Makefile has a single target, `contracts`, which runs a generator in `pkg/contracts/cmd/contractsgen`.

Editorial conclusion

Adopt CrowdSec Manager if you already run CrowdSec and want a single place to read decisions and alerts, manage allowlists and scenarios, and drive the stack through a UI, including from a phone. Do not adopt it expecting it to be a CrowdSec replacement, since it manages the stack rather than doing detection, and check first what you are granting it, because the Docker socket mount gives it control over the host's containers, which is the broadest permission in the whole setup.

Frequently asked questions

Official sources

1. hhftechnology/crowdsec_manager on GitHub
2. Issues
3. Project website
4. README
5. Releases