Swarmpit: a self-hosted UI and API for Docker Swarm clusters

The gap Swarmpit fills: Swarm has no first-party console

Docker Swarm ships with a CLI and an API. It does not ship with a browser interface. Once a cluster has more than a couple of nodes, checking which service has a task stuck in a restart loop means running docker service ps and reading the output by hand. Swarmpit exists to close that gap. The README describes it as a "simple and easy to use interface for your Docker Swarm cluster", covering stacks, services, secrets, volumes and networks. The audience is narrow and specific: teams that have already committed to Swarm mode and want a console they host themselves. The README states that Swarmpit is "completely self-hosted and will never gather any metrics or other data from you", which is the pitch for anyone who does not want a hosted control plane holding cluster credentials. It is not a general container dashboard. If your workloads run on plain Docker without Swarm initialized, or on Kubernetes, nothing here applies.

Four containers, one overlay network, CouchDB and InfluxDB

The repository's docker-compose.yml describes the whole architecture in about sixty lines. The app service runs swarmpit/swarmpit:latest, binds port 888 on the host to 8080 in the container, and reads two environment variables: SWARMPIT_DB=http://db:5984 and SWARMPIT_INFLUXDB=http://influxdb:8086. It mounts /var/run/docker.sock read-only. The db service is couchdb:2.3.0 and persists application data in the db-data volume at /opt/couchdb/data. The influxdb service is influxdb:1.8, storing cluster statistics in influx-data at /var/lib/influxdb. The agent service runs swarmpit/agent:latest in global mode with DOCKER_API_VERSION=1.44, carries the label swarmpit.agent: 'true', and also mounts the Docker socket read-only. All four join an overlay network named net. The split is deliberate: CouchDB holds application state, InfluxDB holds time-series statistics, and the agent runs on every node to collect from each one. Resource limits are declared per service, from 64M for the agent up to 1024M for the app, so the footprint is bounded and visible rather than implied. The app service is constrained with node.role == manager, which matters because the socket it mounts is the manager's.

Installing Swarmpit and reaching the first screen

The README gives the only dependency plainly: Docker with Swarm initialized, Docker 1.13 and newer, on Linux x86 or ARM. There are three install paths. The package installer is interactive and mounts the Docker socket:

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

The README labels this the stable milestone version and offers swarmpit/install:edge as the alternative, described as "latest version for the brave and true". Note the tag: the installer is pinned at 1.9 while the newest release listed in the repository is 1.10, so the stable installer and the newest release are not the same thing.

Manual installation clones the repository and deploys the stack file directly:

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

For ARM clusters the README points at a separate file, docker-compose.arm.yml, deployed the same way. After the stack converges, Swarmpit answers on port 888. The README states that by default Swarmpit asks you to configure the first user through the web interface; automating that step means supplying a users.yaml file through a Docker config, documented in doc/USER_CONFIG.md. Private registry deployment works after linking a Docker Hub account or a custom registry. Everything the UI does is also available over REST, with Swagger docs at /api-docs on any running instance.

Driving Swarmpit from an MCP client

The AI-facing part of the project is a separate repository, swarmpit/mcp, rather than code inside this one. The README states that the MCP server runs locally and holds API tokens so they never enter the LLM conversation context. The flow starts in the Swarmpit UI under Profile, then API Access, then Generate token. That token goes into the MCP client configuration:

{
  "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 names Claude Code and opencode as MCP-compatible clients, and points to the mcp repository for the full tool list, redaction modes and multi-instance setup. The design choice worth noting is where the token lives: in the local MCP process, not in the prompt. That is a sensible boundary, and it also means the MCP server is a second component you install and keep updated alongside Swarmpit itself.

What the documentation does not cover

The README is a landing page, not an operations manual. It does not document rollback of a failed stack deployment, and it does not describe an upgrade procedure from one Swarmpit release to the next. The release history makes that gap concrete: 1.9 landed in April 2020 and 1.10 in April 2026, so anyone moving between them is crossing a six-year jump with no documented migration path in the README. The configuration reference lives in a separate document, doc/configuration.md, and the README only links to it, so environment variable behaviour beyond SWARMPIT_DB and SWARMPIT_INFLUXDB has to be read there. The compose file also shows a real operational constraint: the app service is pinned to manager nodes and mounts the Docker socket read-only, which is a meaningful privilege even read-only, because the socket is the cluster's control surface. The README does not discuss what happens if that socket mount is unavailable or if the manager node hosting the app is drained. If you need documented rollback, staged upgrades or a supported migration path, this is not the tool for you.

Swarmpit against Portainer, and when neither fits

The comparison people reach for is Portainer, and the difference is scope rather than features. Portainer manages Docker standalone, Docker Swarm and Kubernetes from one interface. Swarmpit manages Swarm and nothing else. That narrower target is why the stack is four small services with declared CPU and memory limits instead of a larger platform, and why the README can describe the whole deployment in a single compose file. The trade is that Swarmpit gives you nothing if you later move to Kubernetes, while Portainer at least follows you partway. The other honest alternative is the Docker CLI and API directly: Swarmpit's own README states that everything the UI does is exposed via REST, so a team comfortable with scripting could skip the console and call the API, or use the MCP server without the web UI at all. Swarmpit is the wrong tool when the cluster is not in Swarm mode, when the team needs a platform that spans orchestrators, or when audit and rollback requirements exceed what a self-hosted console with an undocumented upgrade path can support.

Licence, maintenance and the upgrade bill

Swarmpit is published under EPL-1.0. That is a permissive-ish licence with a patent grant and a copyleft clause limited to the licensed code itself, but this is not legal advice; if you plan to redistribute a modified Swarmpit, read the licence text in the repository's LICENSE file rather than a summary. Maintenance is visible in the repository facts: the last push was on 2026-08-21, and the repository is not archived. The release cadence is the part to plan around. Between 1.9 in April 2020 and 1.10 in April 2026 there were no listed releases, which means a team that adopted Swarmpit in that window either tracked the master branch or stayed on 1.9. The practical upgrade cost is therefore not the size of the change but the absence of a documented path: the README does not describe how to move CouchDB application data or InfluxDB statistics between versions, and the installer image is still tagged 1.9. Before upgrading a production instance, check ROADMAP.md and the release notes for the version you are moving to, and take a copy of the db-data and influx-data volumes first, since those are the two volumes the README explicitly recommends you place on a shared-volume driver.

Editorial conclusion

Adopt Swarmpit if you already run Docker Swarm and want a small self-hosted console plus an API and MCP server for the same operations, without sending cluster data anywhere. Do not adopt it if you are on plain Docker or Kubernetes, or if you need documented rollback and versioned upgrade paths. Before deploying, verify that Swarm is initialized on the target host, that the manager node constraint in docker-compose.yml matches your topology, and whether the edge image or the 1.9 installer matches the release you actually intend to run.

Frequently asked questions

Official sources

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