Swarmpit: a self-hosted control plane for Docker Swarm clusters

The gap Swarmpit fills between docker stack and a shared console

Docker Swarm mode ships with a CLI and nothing else. Deploying a stack is one command, but answering questions afterwards is not: which node is running a given replica, what a service's environment actually resolved to, which secrets exist, which overlay networks are attached to which stack. The README frames the project as a simple interface for managing stacks, services, secrets, volumes and networks, and that list is the honest scope statement. Swarmpit is a console for the objects Swarm already has.

The second audience is teams. The README notes you can share the management console with your whole team, and the user configuration documentation describes a users.yaml file supplied through a Docker config so that first-user setup can be automated rather than clicked through in a browser. A separate document covers user types, which implies more than one role exists. That combination, shared access plus scriptable provisioning, is what separates Swarmpit from a personal dashboard.

The third audience is newer and stated in the project's own tagline: AI-friendly. The README points to an MCP server at swarmpit/mcp, so an MCP-compatible client can drive the same operations the UI performs. If your team already runs Swarm and wants an assistant to inspect or deploy against it, that path exists today.

Four services, two databases, and where state actually lives

The manual installation path deploys a stack that the README describes as a composition of four services: app (Swarmpit itself), agent (a separate repository, swarmpit/agent), db (CouchDB) and influxdb (InfluxDB). The split is the architecture in miniature. CouchDB persists application data, meaning users, stacks, services and the rest of the managed objects. InfluxDB stores cluster statistics, which is a different workload with a different retention shape. Keeping them apart means a statistics write spike does not contend with the document store.

The agent is the piece worth pausing on. Swarmpit does not talk to the Docker socket from the app container alone; a separate agent service is deployed alongside it. The README does not describe the agent's protocol or transport, so treat that boundary as undocumented in the supplied material. What can be said is that it is a distinct deployable, which means it can be updated on its own schedule and can fail on its own.

The application itself is written purely in Clojure with React on the front end, per the development section. That is an unusual stack for this category and it shapes the contribution surface: a bug fix in the API layer and a bug fix in the UI live in the same repository but in different languages, and the build is driven by the GitHub Actions workflow referenced in the README badge.

Everything the UI does is also exposed through a REST API, with Swagger documentation served at /api-docs on any running instance. That claim matters more than the UI feature list, because it means the console is not a privileged path. Automation, the MCP server and the browser all exercise the same surface, so a capability that exists in the UI should exist in the API. The README states the equivalence; it does not enumerate the endpoints, so the Swagger page on your own instance is the place to confirm coverage.

Installing it: the installer image versus the compose file

There are two routes. The installer is an interactive container that walks through setup, and it comes in two tags. The stable tag is pinned to a milestone release:

docker run -it --rm --name swarmpit-installer --volume /var/run/docker.sock:/var/run/docker.sock swarmpit/install:1.9

The edge tag is the same command with swarmpit/install:edge instead, which the README describes as the latest version for the brave and true. Note the asymmetry: the installer image tags do not track the application release list in the README header, where 1.10 is the most recent entry. If you want 1.10 specifically, the installer route may not be the one that gets you there, and the manual route is the alternative.

The manual route clones the repository at the branch matching your version and deploys the compose file:

git clone https://github.com/swarmpit/swarmpit -b master docker stack deploy -c swarmpit/docker-compose.yml swarmpit

For ARM clusters the README directs you to a separate file, docker-compose.arm.yml, which is the same command with a different -c argument. The README states that Linux hosts on x86 and ARM are supported and that Docker 1.13 or newer is the floor.

Two operational details are stated plainly. Swarmpit is published on port 888 by default, and the README strongly recommends specifying volumes for db-data and influxdb-data using a shared-volume driver of your choice. The alternative it offers is pinning the db service to a specific node with a placement constraint, which trades durability for simplicity. Neither option is a default you should accept without deciding. The README also notes you can edit the stack file to change the application port, and points to doc/configuration.md for environment variables rather than listing them inline.

Driving Swarmpit from an MCP client without leaking tokens

The MCP integration is the most specific design decision in the README. You generate a token in the Swarmpit UI under Profile, then API Access, then Generate token. That token goes into the configuration of a local MCP server process, not into a prompt:

{ "mcpServers": { "swarmpit": { "command": "npx", "args": ["github:swarmpit/mcp"], "env": { "SWARMPIT_URL": "https://swarmpit.example.com", "SWARMPIT_TOKEN": "your-api-token", "SWARMPIT_REDACT": "sensitive" } } } }

The README is explicit about why: the server runs locally and holds API tokens, so they never enter the LLM conversation context. That is a meaningful boundary. The model sees tool results, not credentials. The SWARMPIT_REDACT environment variable is set to sensitive in the example, and the README says the mcp repository documents the full set of redaction modes along with the tool list and multi-instance setup. Those details are not in this repository, so anyone evaluating the security posture has to read the other one.

One consequence is worth stating. Because the MCP server is a thin client over the same REST API, its capabilities are bounded by that API. If an operation is not exposed at /api-docs, no MCP tool can perform it. The README's claim that everything the UI does is also exposed via the REST API is therefore load-bearing for the AI-facing story, not just a nice property for scripters.

Where Swarmpit is the wrong tool

Swarmpit manages Swarm. It does not extend it. If your requirements include horizontal pod autoscaling driven by custom metrics, admission control, or operators that reconcile desired state continuously, Swarm mode does not provide those primitives and no console can add them. Swarmpit will show you a service with a fixed replica count, and that is the whole story. Choosing Swarmpit is a decision to accept Swarm's model, made before you open the UI.

The release cadence is the second thing to weigh. The release list shows 1.8 in November 2019, 1.9 in April 2020, and then 1.10 in April 2026. That is a six-year gap between 1.9 and 1.10. The repository's last push is dated 2026-08-21 and it is not archived, so work is happening, but the version history tells you the project has gone long stretches without a tagged release. Anyone who needs predictable upgrade windows with security patches on a schedule should treat that pattern as a risk rather than assume the 1.10 tag marks a return to regular cadence. The README points to ROADMAP.md for future and past releases, which is the document to read before committing.

The deployment model has its own constraint. Swarmpit, its agent, CouchDB and InfluxDB all run on the cluster they manage. If the cluster is unhealthy enough that the Swarmpit services cannot be scheduled, the console you would use to diagnose the problem is one of the casualties. A single-node Swarm is the worst case here, since there is no second node to reschedule onto. The README's suggestion to pin the db service to a specific node with a constraint makes this sharper, not better, because it concentrates the failure rather than distributing it.

Portainer and the difference between a Swarm console and a fleet console

The obvious comparison is Portainer, which also offers a Docker Swarm management interface and is also self-hosted. The difference in approach is scope. Portainer is built to manage multiple environments from one installation: several Swarm clusters, standalone Docker hosts, and Kubernetes, with the Swarm view as one mode among several. Swarmpit manages the cluster it is deployed into. Its four-service stack is deployed onto the Swarm it administers, and the README describes no notion of registering additional clusters.

That narrower scope shows up in the storage layer. Swarmpit commits to CouchDB for application data and InfluxDB for cluster statistics, both deployed as part of the stack. A multi-environment tool cannot make that assumption as cleanly, because it needs a control-plane store that outlives any single cluster. Swarmpit's design is coherent precisely because it does not try to be that.

The trade-off is real in both directions. If you run one Swarm and want the console to live inside it, with statistics collection built in and no separate control plane to host, Swarmpit's shape is a better match than a general-purpose fleet manager. If you run several clusters, or you expect to add Kubernetes later, Swarmpit gives you no path to consolidate, and you would end up running it once per cluster. The MCP story is the other axis where Swarmpit differentiates: the README documents a published MCP server with token isolation and redaction modes, which is a more specific AI-integration claim than a generic REST API.

Licence, upgrade cost and what to check before you deploy

Swarmpit is published under EPL-1.0. That is a file-level copyleft licence, which is weaker than GPL in scope: modifications to EPL-licensed files generally must be made available under the same licence, while separate works can be distributed under other terms. This is a summary of the licence's general shape, not legal advice. If you intend to fork Swarmpit, embed it in a product, or modify the app service, read the licence text and the notices in the repository, and get a lawyer involved if the answer affects revenue.

The upgrade cost is dominated by the data services rather than the application. The README recommends persistent volumes for db-data and influxdb-data, and both CouchDB and InfluxDB have their own upgrade paths and their own compatibility rules. Upgrading the Swarmpit app service without a plan for those two stores is the failure mode to avoid. Because 1.9 and 1.10 are six years apart, the jump between them is not a routine patch and the ROADMAP.md file is the right place to start reading about what changed.

Three things to verify before you commit. First, confirm your Swarm is initialised and that the Docker version is 1.13 or newer, since the README names that as the only dependency. Second, decide where db-data and influxdb-data live and configure the volume driver or the placement constraint accordingly, rather than letting the default land on a node you have not chosen. Third, open /api-docs on the running instance and check that the operations you care about are actually there, because the MCP server and any automation you build sit on top of that surface. If an operation is missing from Swagger, it is missing from everything except the browser.

Editorial conclusion

Adopt Swarmpit if you already run Docker Swarm mode and want a shared console for stacks, services, secrets, volumes and networks without handing cluster credentials to a hosted vendor. Skip it if your workloads need autoscaling, custom controllers or anything Kubernetes provides. Before deploying, verify that your Swarm is initialised, that you can supply persistent volumes for the db-data and influxdb-data paths, and that you have read doc/configuration.md for the environment variables the app service expects.

Official sources

1. License: EPL-1.0
2. Project website
3. README
4. Releases
5. swarmpit/swarmpit on GitHub