Uncloud

Uncloud is a lightweight clustering and container orchestration tool that lets you deploy and manage web applications across cloud VMs, dedicated servers, and bare metal using familiar Docker Compose files. It creates a secure WireGuard mesh network between your Docker hosts and provides automatic service discovery, load balancing, HTTPS ingress, and simple CLI commands — all without running a central control plane.

Unlike traditional orchestrators, Uncloud takes a decentralized approach where every machine maintains a synchronized copy of cluster state through peer-to-peer communication powered by Corrosion, a CRDT-based distributed SQLite. This means cluster operations stay functional even when individual machines go offline, and there is no quorum to maintain or etcd cluster to babysit.

Uncloud favours imperative operations over state reconciliation, making it much easier to reason about what is actually happening and to troubleshoot when things go wrong. You initialize machines over SSH, deploy services with a single command, and get production-grade networking, HTTPS, and DNS out of the box on infrastructure you own — whether that is a $5 VPS, a spare Mac mini, or a rack of bare metal servers.

The project is in active development with frequent releases (averaging roughly two per month) and a growing community, though it explicitly notes it is not yet ready for production. It targets developers and small teams who want the cloud-platform experience without vendor lock-in or the operational complexity of Kubernetes.

What You Get

• Docker Compose Compatibility - Deploy services using standard docker-compose.yaml files including build sections, volumes, environment variables, healthchecks, devices, ulimits, and deploy constraints — no proprietary DSL to learn.
• Automatic WireGuard Mesh Network - Machines are connected via an encrypted peer-to-peer WireGuard overlay with automatic NAT traversal; each machine gets a dedicated subnet (e.g. 10.210.0.0/24) so containers communicate directly across providers.
• Built-in Caddy Reverse Proxy with Automatic HTTPS - Every service with a published port gets free TLS via Let’s Encrypt automatically; the Caddyfile is regenerated dynamically as containers start and stop without any manual configuration.
• Decentralized Cluster State via Corrosion CRDTs - No central control plane or quorum; each node maintains a synchronized copy of cluster state through Corrosion (a distributed SQLite backed by CRDTs), keeping operations available even when machines go offline.
• Unregistry Integration for Efficient Image Distribution - Build images locally and push them directly to cluster machines without an external registry; only missing layers are transferred, making incremental builds fast even on slow connections.
• Built-in Service Discovery DNS - An internal DNS server resolves service names (e.g. db.internal, web.internal) and nearest-replica addresses to container IPs, updating automatically as containers are deployed or removed.
• Zero-Downtime Rolling Deployments with Health Monitoring - Rolling updates start new containers before stopping old ones; deployment monitors container health checks and crash loops, automatically rolling back if the new version becomes unhealthy.
• SSH-based Remote Management - Control the entire cluster through SSH to any single machine; no API keys, no open inbound ports, no separate control plane to maintain.
• GPU and Device Support - Services can request GPU resources and map host devices through standard Compose attributes (gpus, deploy.resources.reservations.devices, devices), enabling ML and media processing workloads.
• Managed DNS Subdomains - Free *.xxxxxx.uncld.dev subdomains are automatically provisioned and updated via the Uncloud DNS service, giving public HTTPS access to services without any DNS provider configuration.

Common Use Cases

• Self-hosting a web application across multiple VPS providers - A developer combines a Hetzner VPS and an Oracle Cloud free-tier instance into one Uncloud cluster, deploys a multi-container app with a single uc deploy command, and gets automatic HTTPS on their custom domain without touching Nginx configs or certificate renewals.
• Running stateful services with volume persistence across bare metal - A team deploys PostgreSQL with Docker volumes across two on-premises servers, using Uncloud’s persistent storage management and service discovery so the application tier can always reach db.internal regardless of which node the container is running on.
• Building and deploying from source in CI/CD without a container registry - A startup configures the build section in their Compose file so uc deploy builds images locally, tags them with the git commit hash, and pushes them directly to cluster machines via Unregistry — no Docker Hub account, no registry infrastructure to maintain.
• Deploying GPU workloads across heterogeneous edge nodes - A video processing team maps host GPU devices into containers using Compose’s devices and gpus attributes, distributing transcoding jobs across machines with different hardware without needing Kubernetes device plugins or node selectors.
• Scaling a high-availability service across geographic regions - An indie developer runs their SaaS on three VPS instances in different regions, using Uncloud’s global services mode to ensure one replica runs on each machine, with Caddy distributing traffic and health checks triggering automatic rollback if a deployment fails.

Under The Hood

Architecture Uncloud follows a layered but tightly integrated architecture where the machine daemon (uncloudd) acts as both the gRPC server for cluster operations and the runtime host for all subsystems — WireGuard network management, Corrosion CRDT store, Caddy configuration controller, Docker integration, and DNS server. The CLI (uc) communicates with any machine’s daemon over SSH tunnels or a local Unix socket, and the daemon proxies requests to other cluster members transparently. This design eliminates the need for a dedicated control plane but means the daemon is a large monolith that couples network, storage, and application management concerns in a single process. State synchronization uses Corrosion, a CRDT-based distributed SQLite that replicates via peer-to-peer gossip between all daemons, providing eventual consistency with no quorum requirement. The deployment system uses an operation-based model where planned changes (start container, stop container, replace container) are computed client-side and executed sequentially with rollback support.

Tech Stack Uncloud is written entirely in Go (89% of codebase) targeting Go 1.26, using Cobra for CLI command structure and the Charm ecosystem (Bubbletea, Huh, Lipgloss) for interactive TUI elements. The daemon embeds Caddy v2 configuration management, the Docker Engine client and Compose v2 libraries for container lifecycle, gRPC with Protocol Buffers for inter-daemon communication, and WireGuard kernel integration via wgctrl. Cluster state is stored in Corrosion (a fork of Superfly’s CRDT-based distributed SQLite). The build toolchain uses mise for reproducible development environments, golangci-lint for static analysis, and protoc for protobuf code generation. End-to-end tests use a custom ucind (Uncloud-in-Docker) cluster simulation environment running in Docker-in-Docker.

Code Quality The codebase has extensive test coverage across unit, integration, and end-to-end levels — 51 test files with 124 test functions, including a comprehensive e2e suite that validates cluster initialization, service deployment, Compose configs, exec, and build workflows against real Docker environments. Error handling is consistent, using fmt.Errorf with %w for context-preserving wrapping and well-typed gRPC status codes for API errors. Package structure follows Go conventions with internal/ for daemon internals, pkg/ for the public client API, and cmd/ for CLI entrypoints. The caddyconfig package demonstrates strong separation of concerns with fingerprint-based change detection to avoid redundant Caddy reloads. There are some areas of tight coupling — the main Machine struct in internal/machine imports most subsystems directly — but overall naming, documentation, and type safety are at a high standard for an early-stage project.

What Makes It Unique Uncloud’s most distinctive technical choice is its use of CRDT-based distributed SQLite (Corrosion) as the cluster store rather than a consensus-based system like etcd or Raft. This allows any number of machines to go offline without affecting the remaining cluster, and there is no quorum threshold to configure or worry about. The Caddy integration is code-driven rather than file-template-based: a controller watches the Corrosion store for container changes, computes container fingerprints to detect meaningful diffs, and generates Caddyfile configurations programmatically — enabling zero-touch HTTPS without any user-managed config files. The Unregistry integration for registry-free image distribution, combined with git-tag-based image versioning baked into the deploy workflow, creates an unusually smooth build-push-deploy cycle for teams that do not want to operate a container registry.

Self-Hosting

Uncloud is released under the Apache License 2.0, one of the most permissive open-source licenses available. You can use it commercially, modify the source code, distribute it, and incorporate it into proprietary products without any copyleft obligations. The only requirements are preserving copyright notices and the license file. There are no open-core restrictions, license keys, or enterprise editions — the entire codebase on GitHub is the product.

Running Uncloud yourself requires Linux machines with Docker installed (the daemon only runs on Linux, though the CLI works on macOS and Windows). You provision machines by SSH-ing into them from the uc CLI, which downloads and installs the daemon automatically. Operationally, you are responsible for the Linux hosts, their Docker runtimes, network firewall rules (WireGuard uses UDP port 51820), SSH access, and hardware uptime. There is no built-in high-availability for the daemon itself — if a machine running containers goes down, those containers stop until the machine recovers. Backups of persistent Docker volumes are entirely your responsibility. The project explicitly states it is not yet production-ready, so evaluators should factor in the operational risk of running pre-v1.0 software in critical environments.

There is currently no hosted or managed version of Uncloud, no commercial support tier, and no SLA. If you need guaranteed uptime, managed upgrades, or professional support, you would be looking at alternatives like Fly.io, Render, or Railway on the managed side, or a supported Kubernetes distribution like EKS or GKE on the self-hosted-but-supported side. The trade-off you make by self-hosting Uncloud is full control and zero platform fees in exchange for owning all operational responsibilities and accepting the maturity risks of early-stage software.