Accessing a Docker Swarm cluster often feels like a choice between two extremes: complex VPN/SSH tunneling or the risky exposure of the raw Docker Engine socket.
With the introduction of the SwarmCLI Proxy, we've built a third way—a dedicated security and orchestration layer designed to harden your cluster while simplifying how you manage access. This isn't just an update; it's a foundational shift in how SwarmCLI protects your infrastructure.
The Problem: The "Direct Socket" Vulnerability
By default, Docker Engine's remote API follows a "flat" security model. If you have access to the socket (usually via DOCKER_HOST), you effectively have root-level control over the entire node.
Native Docker Swarm vs. SwarmCLI Proxy
| Feature | Native DOCKER_HOST Access |
SwarmCLI Proxy |
|---|---|---|
| Authentication | None (Plain TCP) or Manual mTLS | Native, Automated mTLS |
| Granularity | All-or-nothing | Foundational RBAC Support |
| Infrastructure Guarding | None (accidental rm -rf possible) |
Middleware Protection (Blocking Deletes) |
| User Onboarding | Manual cert issuance/rotation | Token-based context provisioning |
| Logging | Engine-level only | Proxy-level audit trails |
Core Pillars of the SwarmCLI Proxy
The SwarmCLI Proxy was built to solve the "last mile" of Swarm security. By acting as a specialized middleware between you and the Docker Engine, it provides features that the native Engine simply wasn't designed for.
1. Zero-Friction mTLS Automation
Setting up Mutual TLS (mTLS) for Docker is notoriously tedious. It involves manual CA creation, CSR signing, and fragile certificate rotation.
The SwarmCLI Proxy streamlines this lifecycle. By setting PROXY_TLS_CLIENT_CA_KEY and a PROXY_SEED_USERNAME during your stack deployment, the proxy initializes an internal Certificate Authority (CA) and auto-issues a client certificate strictly for your seeded admin user. From there, you get an enterprise-grade encrypted foundation, though any additional team members must be configured and onboarded separately.
2. Safeguarding Critical Infrastructure
Even for senior engineers, accidents happen. A misplaced docker network rm or docker stack rm can bring down an entire production cluster.
The Proxy introduces Infrastructure Guards. It intercepts these high-risk commands and validates them against the cluster's health. For example, it by default blocks the deletion of the swarmcli-agent-net overlay, ensuring that your monitoring and management layer remains untouched even by administrative error.
3. Native persistence with SQLite
Unlike simple stateless proxies, the SwarmCLI Proxy includes a persistent SQLite store (with optional PostgreSQL support for high-availability clusters). This allows it to statefully manage:
- One-time onboarding tokens for secure, automated context provisioning.
- User-to-role mappings (enforcing foundational RBAC rules).
- Persistent audit logs of who accessed the cluster and when.
Operational Workflow: The Deployment Experience
Bringing this security layer to your cluster simply involves deploying the official stack with your seed environment variables.
# Initialize the proxy on your cluster
docker stack deploy -c stack.yml rbac
During initialization, the proxy automatically:
- Detects its environment and provisions a protected
rbac-proxyservice. - Bootstraps the first administrative user via
PROXY_SEED_USERNAME. - Configures the internal SQLite database and mTLS Certificate Authority.
Architecture: The Dual-Listener Design
The SwarmCLI Proxy utilizes a hardened networking model to ensure it remains the "single source of truth" for cluster access:
-
Admin-Only Listener (127.0.0.1:2375): A local, non-authenticated port for local management, node-level automation, and safe
docker execaccess. - Security Listener (0.0.0.0:2376): The public-facing mTLS port. It enforces client-certificate verification for every request, rejecting any traffic from users not found in the persistent store and effectively "cloaking" the Docker API from unauthorized scanners.
The Path Forward: Scaling to Teams
While the current version focus on hardening the primary administrative connection, the architecture is ready for scale. The SwarmCLI Proxy is the engine that will power our upcoming multi-user RBAC system, allowing teams to grant "Read-Only" or "Namespace-Direct" access to developers without handing over the keys to the kingdom.
Secure Your Swarm Today
The SwarmCLI Proxy is available now, and will be part of the upcoming SwarmCLI v1.5.0 release.
View the Installation Guide | Read the Documentation
Why SwarmCLI?
By 2026, we noticed a gap. Docker Swarm was rock solid, but the management tooling felt stuck in 2017. SwarmCLI bridges that gap with:
Real-time Health: Stop guessing which node is throttled.
Atomic Secret Sync: One-command .env to Raft encryption.
Edge-Optimized: Built in Go for zero-overhead on ARM/RPi5 devices.