Uncloud: a WireGuard mesh and a Docker-like CLI for multi-host containers

The gap Uncloud is aiming at: multi-host Docker without a control plane

Docker Compose is comfortable on one machine and awkward on five. You either copy the file around and manage ports by hand, or you move to Swarm or Kubernetes and inherit a control plane, quorum, and a YAML vocabulary you did not ask for. Uncloud's README states the project exists for the space between those two options: people who want to combine cloud VMs, dedicated servers and bare metal into one environment without what it calls the operational complexity of Kubernetes. The stated audience is developers who want self-hosted infrastructure, not platform engineers running a shared cluster for an organisation. That distinction matters. Uncloud is opinionated about being small: the README says the design has no central control plane and no quorum, with each machine keeping a synchronised copy of cluster state through peer-to-peer communication. The pitch is that cluster operations keep working when some machines go offline. Whether that holds under partition is not something the supplied material demonstrates, and the README does not describe a conflict resolution rule.

WireGuard mesh, peer-synced state, and Caddy at the edge

The architecture visible in the README has four moving parts. First, a WireGuard mesh: the tool creates a private network between Docker hosts with peer discovery and NAT traversal, and containers get unique IPs so they can talk across machines directly. Second, replicated state: there is no central control plane, and each machine holds a synchronised copy of cluster state. Third, service discovery and ingress: a built-in DNS server resolves service names to container IPs, and a bundled Caddy reverse proxy handles TLS certificate provisioning and renewal via Let's Encrypt. Fourth, image distribution: the README points at a companion project, unregistry, which lets you build and push images straight to your machines with no external registry, transferring only the missing layers. The README also notes an imperative rather than declarative model, arguing it simplifies both the mental model and troubleshooting. That is a real design commitment, not marketing: it means the tool applies operations when you issue them rather than continuously reconciling toward a desired state. The practical consequence is that drift between what you declared and what is running is your problem to notice, not the controller's.

Getting from zero to a deployed service

The README's quick start is four steps. Install the CLI with Homebrew or the install script:

brew install psviderski/tap/uncloud

or

curl -fsS https://get.uncloud.run/install.sh | sh

Then initialise the first machine over SSH:

uc machine init root@your-server-ip

Then deploy from an image and publish a port:

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

That last command is the interesting one. The `-p` flag takes a host, a container port and a scheme, and the README says it exposes container port 8000/tcp as HTTPS on app.example.com, served by the Caddy reverse proxy on the remote machines. The fourth step, creating a DNS A record, is where the README excerpt ends, so the exact record contents are not in the supplied material. The README separately mentions managed DNS records of the form `*.xxxxxx.uncld.dev` for services with public access, handled by a companion uncloud-dns service, which is the alternative to pointing your own domain at the cluster. Applications are defined in Docker Compose format rather than a bespoke DSL, and the repository ships its own website/compose.yaml as the worked example. Remote management works through SSH access to any single machine in the cluster, so you do not need a VPN into the network to run `uc` commands.

What is missing: rollback, and the cost of imperative operations

The README is explicit that automatic rollback on failure is coming soon. Until it lands, a bad release is something you unwind yourself, and the imperative model gives you no reconciliation loop to fall back on. The same section advertises zero-downtime rolling updates, so the gap is specifically recovery, not deployment. There is a second limitation that follows from the decentralised design: every machine holds a copy of cluster state, which the README presents as an availability benefit. It also means there is no single place to inspect authoritative state when two nodes disagree. The README does not describe what happens during a network partition or how conflicting writes are ordered, and I cannot confirm the behaviour from the supplied material. A third constraint is the WireGuard dependency. If your hosts sit behind a provider that blocks the required traffic, or your compliance rules forbid a mesh overlay, the core mechanism is unavailable and the rest of the tool does not stand alone. Finally, the release cadence tells you something about maturity: a nightly rolling build sits alongside tagged releases such as v0.20.0 and v0.19.0, and the README invites you to try nightly for features that have not shipped officially. That is a project still moving quickly, and the version you pin matters.

How this differs from Kubernetes and from plain Docker Compose

Kubernetes and Uncloud solve overlapping problems with opposite defaults. Kubernetes gives you a declarative API, a control plane with etcd and quorum, and a controller that continuously reconciles actual state toward desired state. Uncloud deliberately removes the control plane, replicates state across peers, and applies operations imperatively. The difference shows up in failure modes: lose quorum in Kubernetes and the API stops accepting changes; lose a node in Uncloud and, per the README, the remaining machines keep operating because each holds a copy. The cost is that Kubernetes has a decade of tooling for exactly the questions Uncloud leaves open, such as what happens under partition and how to roll back a bad deploy. Against plain Docker Compose the comparison is simpler. Compose on a single host gives you no cross-machine service discovery, no mesh networking, no ingress with automatic certificates, and no rolling update. Uncloud keeps the Compose file format and adds those four things. If you are running one server, Compose plus a reverse proxy is less machinery. The case for Uncloud starts when the second and third host appear.

Licence, releases and what maintenance actually involves

Uncloud is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notice files, and it includes a patent grant. That is a permissive licence, and this is not legal advice; check with your own counsel if you plan to redistribute a modified version. On maintenance, the material supports a few concrete observations. The project publishes tagged releases roughly every two months based on v0.19.0 in April and v0.20.0 in June, plus a nightly build. There is a Discord server and a sponsors link in the README, which suggests a small team or a single maintainer rather than a foundation-backed project. The two companion repositories, unregistry and uncloud-dns, mean your operational surface is not one binary: image distribution and managed DNS are separate services you may end up running. Upgrades are a CLI install plus whatever the release notes specify for the machines, and the README does not describe a cluster-wide upgrade command, so plan on touching hosts individually. Because state is replicated peer to peer, a botched upgrade on one node is a question about how the rest of the mesh reacts, and the README does not answer that.

Who should adopt it, and what to check first

Adopt Uncloud if you are a developer or a small team running containers on two to ten self-managed machines, you already write Docker Compose files, and you would rather not run a Kubernetes control plane. The Compose format and the `uc` command names lower the learning cost, and the bundled WireGuard mesh plus Caddy ingress removes two pieces of infrastructure you would otherwise assemble yourself. Do not adopt it if you need automatic rollback today, if your hosts cannot form a WireGuard mesh, or if you are running at a scale where a real control plane and its ecosystem are worth the overhead. Before committing, verify on your own hardware that `uc machine init` succeeds on every host and that the mesh actually forms, that `uc run -p host:port/https` provisions a certificate through the bundled Caddy rather than silently falling back to HTTP, and that either your own A records or the managed `*.uncld.dev` path resolve correctly. Then read the release notes for the exact version you pin, because the nightly and tagged builds are separate tracks and the README points at both.

Editorial conclusion

Uncloud fits developers running a handful of self-managed VMs or bare-metal boxes who already know Docker Compose and do not want to operate a control plane. It is the wrong tool if you need automatic rollback (the README lists it as coming soon), if your platform team has already invested in Kubernetes tooling, or if you cannot run WireGuard between your hosts. Before adopting, verify three things on your own machines: that `uc machine init` completes on each host and the mesh forms, that `uc run -p host:port/https` actually provisions a certificate through the bundled Caddy, and that the managed `*.uncld.dev` DNS path or your own A records resolve to the right node. Also read the release notes for the version you pin, because the project ships a nightly build alongside tagged releases and the two can diverge.

Official sources

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