psviderski/uncloud: a Docker-host cluster with no control plane, and where the gaps are

Every machine keeps its own copy of cluster state, so there is no quorum to lose

Uncloud describes itself as a tool for deploying and managing containerised applications across a network of Docker hosts. The design choice that sets it apart is the absence of a central control plane. Each machine holds a synchronised copy of the cluster state, exchanged through peer-to-peer communication, so cluster operations keep working even if some machines go offline.

Under that sits a WireGuard mesh with peer discovery and NAT traversal, which gives containers unique IPs for direct cross-machine communication. Management goes through SSH access to any single machine in the cluster. The consequence is that you never have to keep a set of control nodes healthy, but you also have no single dashboard or API server to ask for the truth about the cluster. The state lives on the machines themselves.

Two install routes and a four-command path to a running HTTPS service

The CLI installs through Homebrew or a curl script, and a nightly rolling release exists for anyone who wants fixes before they land in an official release. The first machine is initialised over SSH, then a service is started from an image.

brew install psviderski/tap/uncloud

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

uc machine init root@your-server-ip

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

The run command publishes container port 8000 as HTTPS under the domain you give it. The curl route pipes a remote script into a shell, so read the script first if the target is a production server. Cleanup is `uc ls` to find the service name, then `uc rm my-app-name`, and `uncloud-uninstall` removes Uncloud from a machine entirely.

The domain still needs a DNS A record you create by hand

After the run command, the README adds a step that the tool does not perform for a custom domain: create a DNS A record at your provider, such as Cloudflare or Namecheap, pointing app.example.com to your server's IP address, then wait a few minutes for propagation. Only after that is the app reachable at the HTTPS address.

For services that need public access without bringing a domain, the README lists a managed option: automatic DNS records of the form `*.xxxxxx.uncld.dev`, served by the separate Uncloud DNS service. That ties those names to a service run by the project, so a team with a strict no-external-dependency rule should use its own domain and its own records. Caddy handles certificate provisioning and renewal through Let's Encrypt, and the certificates and ACME challenge tokens are shared through cluster storage across machines.

Rolling updates work today, automatic rollback is marked as coming soon

Zero-downtime deployments are listed as rolling updates without service interruption. The same line says that automatic rollback on failure is coming soon, which means it is not shipped. If a new image starts but misbehaves, nothing in the feature list says Uncloud will return to the previous version for you.

The design philosophy points the same way. The README says it favours imperative operations over state reconciliation, to simplify the mental model and troubleshooting. The practical result is that you run the commands that move the cluster, and recovery from a bad release is a command you issue yourself, for example by deploying the previous image again. Plan for that with a known-good image tag before you rely on rolling updates for anything customer-facing.

Compose files and image transfer through Unregistry instead of an external registry

Services and volumes are defined in the Docker Compose format, with no bespoke DSL to learn. The quick demo deploys the uncloud.run website to 2 remote machines from a compose.yaml on the local machine, exposing container port 8000/tcp as HTTPS on the uncloud.run domain through Caddy.

Images move through Unregistry, a separate project by the same author. It builds and pushes Docker images directly to your machines without an external registry, transferring only the missing layers. The go.mod file requires github.com/psviderski/unregistry v0.4.1, github.com/compose-spec/compose-go/v2 v2.9.0, and github.com/caddyserver/caddy/v2 v2.11.4, and the module targets go 1.26.0. For stateful services, persistent storage means Docker volumes managed across machines, so check how a given volume behaves on each host before moving a database onto it.

The corrosion image is built for amd64 and arm64 only

The Dockerfile has a stage that downloads a corrosion release from github.com/psviderski/corrosion and installs it as /usr/bin/corrosion, and the final corrosion image runs `corrosion agent`. The download stage maps amd64 to x86_64 and arm64 to aarch64, and any other TARGETARCH exits with the message that the architecture is not supported.

A comment in the Dockerfile adds a warning about base images: more modern images such as chainguard/wolfi-base build glibc with flags that require newer CPU features such as x86-64-v2, and can fail with Fatal glibc error: CPU does not support x86-64-v2 on older CPUs. That is why the image uses gcr.io/distroless/cc-debian13. If you build your own image on old hardware, keep that failure in mind. The Makefile pins CORROSION_VERSION to 2026.6.15 and pushes multi-arch images for linux/amd64 and linux/arm64.

A 0.x release line with a nightly build one day after the last push

Releases are v0.20.0 on 2026-06-26, v0.21.0 on 2026-10-02, and a nightly build on 2026-10-29, which matches the last push date. The project is not archived. The version numbers stay below 1.0, so treat the CLI flags and the cluster behaviour as subject to change between minor releases and read release notes before upgrading machines in a live cluster.

The repository layout shows how the project tests itself: a ucind image for running Uncloud-in-Docker test clusters, a make target `ucind-cluster` that creates three machines by default, and an end-to-end suite under test/e2e. A comment at the top of the Makefile says it is deprecated and new targets should become mise tasks in mise.toml. Contributors should expect that move. Apache-2.0 is the license.

Editorial conclusion

Uncloud suits a developer with a few VMs or bare metal boxes who wants Compose files, HTTPS, and a mesh network without running Kubernetes. It is a 0.x project whose automatic rollback is still unreleased, so check how you would recover a bad deploy before putting anything critical on it.

Frequently asked questions

Official sources

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