Why Cetacean?
Docker Swarm doesn't come with a dashboard. You get docker service ls and that's about it. Cetacean fills the gap:
run one container on a manager node and see the whole cluster, with live updates as things change.
It connects to the Docker socket, caches swarm state in memory, and pushes changes to the browser over SSE. No
database, no agents on worker nodes, no configuration required.
Quick start
Run it on a manager node:
docker run -d --name cetacean \
-p 9000:9000 \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-v cetacean_data:/data \
-e CETACEAN_DATA_DIR=/data \
ghcr.io/radiergummi/cetacean:latest
Open http://<manager>:9000. Or deploy the bundled stack, which adds resource limits and pins the task to a
manager:
docker stack deploy -c compose.yaml cetacean
See Getting started for the monitoring and authentication setup.
What you get
- Cluster overview with live health cards, capacity bars, and an activity feed
- Nodes, services, tasks, stacks, configs, secrets, networks, volumes and plugins, all cross-referenced
- Log viewer with live tailing, regex search, JSON formatting, and time range filtering
- Topology views: logical (services grouped by stack, linked by shared overlay networks) and physical (tasks by node)
- Metrics via optional Prometheus integration, plus a PromQL console and sizing recommendations
- Write operations (scale, restart, rollback, image and spec edits, node drain) gated by an operations level
- Pluggable authentication: anonymous, OIDC, Tailscale, mTLS, or trusted proxy headers, with per-resource RBAC
- Web API with search, filtering, pagination, JSON-LD, OpenAPI, SSE, and Atom feeds
- Embedded MCP server, so an AI agent reads and operates the cluster through the same permissions
Comparison
| Portainer | Swarmpit | Cetacean |
|---|
| Deploy complexity | DB + agents + auth | CouchDB + agent | Single container |
| Time to first page | Minutes | Minutes | Seconds |
| Real-time updates | Polling | Polling | SSE push |
| Metrics | Built-in | Built-in | Prometheus |
Documentation
Full documentation is at https://cetacean.mazetti.me, and in docs/ in this
repository:
Build from source
Requires Go 1.27+ and Node.js 24+. make build installs the frontend dependencies, builds the dashboard
and the MCP widgets, and compiles the binary, which embeds both:
make build
./cetacean
Cetacean needs a swarm to connect to; docker swarm init gives you a single-node one for local work. See
CONTRIBUTING.md for the development setup, the dev server, and the make targets.
License
GNU General Public License v3.0
Third-party components bundled with Cetacean are listed in
THIRD_PARTY_LICENSES (includes the Lucide/Feather icon
set used for the UI and the embedded MCP tool and resource icons).
