psviderski/uncloud: Docker Compose Deployments Across a WireGuard Mesh

The gap Uncloud targets between Compose and Kubernetes

A single Docker host with Compose is easy to reason about until the second machine appears. At that point you either keep the two hosts independent, or you move to an orchestrator. Kubernetes answers the second case with a control plane, a quorum of API servers and etcd, and a declarative model where you describe desired state and controllers reconcile it. Uncloud takes the opposite position. The README states that each machine maintains a synchronised copy of the cluster state through peer-to-peer communication, and that there is no central control plane and no quorum to maintain. Cluster operations keep working, according to the README, even if some machines go offline. The audience is explicit: developers who want self-hosted infrastructure without Kubernetes operational complexity, running on cloud VMs, dedicated servers and bare metal, including a spare Mac mini or a $5 VPS. If you already have a Kubernetes cluster that works, Uncloud is not aimed at you.

How the WireGuard mesh and peer-to-peer state work

The unit of installation is a machine, not a container. Running uc machine init against an SSH-reachable host installs an agent, and that agent joins the machine to a WireGuard mesh with peer discovery and NAT traversal, described in the README as zero-config. Containers receive unique IPs so they can talk to each other directly across hosts. A built-in DNS server resolves service names to those container IPs, which is how one service finds another without you hardcoding addresses. State is replicated to every peer rather than centralised, which is the design decision that removes the control plane and also the one that puts a copy of cluster state on each machine. Ingress sits on the hosts as a Caddy reverse proxy; the go.mod file shows caddyserver/caddy and caddyserver/certmagic as dependencies, and the README says Caddy handles TLS certificate provisioning and renewal through Let's Encrypt. Public services can get managed DNS records of the form *.xxxxxx.uncld.dev through a separate Uncloud DNS service, or you can point your own A record at the ingress host.

Installing the Uncloud CLI and deploying a first service

The README gives two installation routes: a Homebrew tap and a curl script for macOS and Linux. Both install the uc binary, which is the client you use for everything afterwards.

brew install psviderski/tap/uncloud

# or using curl (macOS/Linux)
curl -fsS https://get.uncloud.run/install.sh | sh

The README also mentions a nightly rolling release for trying features before they land in an official release. The latest tagged release listed in the repository is v0.20.0 from 2026-06-26; the last push to main was on 2026-09-08.

With the CLI installed, initialise the first machine. This takes an SSH target and installs the agent that joins the machine to the mesh.

uc machine init root@your-server-ip

A first deployment can skip Compose entirely. The README example runs an image, maps container port 8000 to HTTPS on a domain, and lets Caddy obtain the certificate.

uc run -p app.example.com:8000/https image/my-app

After that command, the README's step 4 is to create a DNS A record pointing the domain at the machine, unless you are using the managed uncld.dev names. The repository also ships a compose.yaml for the project's own website, which the README uses as a worked example of deploying to two remote machines from a local Compose file.

Where Uncloud stops: rollback, reconciliation and scale

The README is direct about one missing piece: zero-downtime rolling updates are supported, but automatic rollback on failure is described as coming soon. That means a bad deploy needs a human to notice and re-run a previous image tag; there is no controller watching health and reverting. The second limitation follows from the design. Uncloud is, in the README's words, imperative over declarative, favouring imperative operations over state reconciliation. That simplifies the mental model and troubleshooting, and it also means nothing continuously enforces that the running cluster matches a file. If a container dies or a host is rebuilt, the cluster does not converge back to a declared state on its own the way a Kubernetes controller would. The third is scale and tenancy. There is no mention of autoscaling, resource quotas, namespaces or multi-tenant isolation, so a platform team serving many internal teams should look elsewhere. Finally, the tooling assumes SSH access to the machines and a Compose file that the compose-go parser accepts; anything relying on Compose features outside that parser's support is a risk you should test before migrating.

Uncloud compared with Docker Swarm and Kubernetes

Docker Swarm is the closest comparison in operational weight. Swarm uses managers and workers with a Raft quorum among managers, so you maintain an odd number of manager nodes and accept that losing quorum stops cluster management. Uncloud removes that tier: state is replicated peer to peer, and the README claims cluster operations stay functional when some machines go offline. Kubernetes differs on a second axis as well. Its controllers constantly reconcile observed state toward declared state, which is what makes self-healing and GitOps workflows possible; Uncloud deliberately does not do this, trading convergence for a smaller mental model. If you want the reconciliation model and the ecosystem around it, Kubernetes is the right answer even at the cost of the control plane. If you want Swarm's model without the manager quorum, Uncloud is the more direct substitute. The unregistry integration is a further difference: it lets you build and push images straight to your machines, transferring only missing layers, so you can run without an external registry.

Maintenance, upgrades and the Apache-2.0 licence

The repository is not archived and the last push to main was on 2026-09-08, so development is current as of that date. Release cadence in the listing is uneven: v0.19.0 on 2026-04-24, v0.20.0 on 2026-06-26, then a nightly build on 2026-09-08. The nightly tag means you can track unreleased work, at the cost of running something that is not a tagged release. Upgrading the CLI is the same command as installing it, and the agent on each machine is installed by uc machine init, so a fleet upgrade means revisiting machines rather than flipping one central version. The project is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant; if you redistribute it or embed it in a product, read the NOTICE and attribution requirements in the licence text itself. This is a description of the licence, not legal advice. The Dockerfile pins Alpine 3.23.3 and builds the daemon with CGO disabled, and it notes that the distroless glibc image can fail on older CPUs with a glibc error, which is worth checking if you deploy to aged hardware.

Editorial conclusion

Adopt Uncloud if you run a handful of VMs or bare-metal boxes and want Compose files, WireGuard networking and automatic HTTPS without operating Kubernetes. Do not adopt it if you need autoscaling, a declarative reconciliation loop, or automatic rollback, which the README lists as still coming. Before committing, verify on your own machines that uc machine init completes against your SSH access, that the managed uncld.dev DNS or your own A record resolves to the ingress host, and that your Compose file does not depend on features the compose-go parser rejects.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. psviderski/uncloud on GitHub
4. README
5. Releases