Uncloud is a decentralized container orchestration tool designed for developers who want the simplicity of cloud platforms like Heroku but with full control over their infrastructure. It bridges the gap between basic Docker usage and complex systems like Kubernetes by providing a minimal, self-hosted solution that works across cloud VMs, bare metal servers, and personal hardware. Unlike traditional orchestrators, Uncloud eliminates the need for a central control plane by using peer-to-peer synchronization via CRDTs and WireGuard mesh networking, making it resilient to node failures and ideal for small-to-medium scale deployments.
Built with Go, Uncloud leverages familiar Docker Compose files and a Docker-like CLI to abstract away the complexity of distributed systems. It automatically handles service discovery, load balancing, HTTPS via Caddy, and persistent storage across machines—all while keeping the operational burden low. This makes it particularly valuable for developers, DevOps teams, and hobbyists managing multi-server environments who need reliability without the steep learning curve of Kubernetes.
What You Get
- Docker Compose support - Use standard docker-compose.yaml files to define services, volumes, and networks without learning a custom DSL.
- Zero-downtime deployments - Rolling updates ensure your apps stay online during upgrades; automatic rollback is planned for future releases.
- Automatic WireGuard mesh network - Creates a secure, encrypted overlay network between all hosts with NAT traversal and automatic peer discovery.
- Built-in service discovery - Internal DNS resolves service names to container IPs across the cluster, enabling direct inter-container communication.
- Managed DNS and automatic HTTPS - Services are automatically exposed via *.uncld.dev domains with Let’s Encrypt TLS certificates handled by Caddy.
- No control plane - Decentralized architecture with CRDT-based state sync (via uncloud-corrosion) means no single point of failure and minimal maintenance.
- Remote management via SSH - Control your entire cluster from any machine in the network using simple CLI commands over SSH.
- Unregistry integration - Build and push Docker images directly to cluster nodes without an external registry, transferring only missing layers for efficiency.
- Persistent storage across machines - Docker volumes are synchronized and accessible from any node in the cluster, enabling stateful applications.
Common Use Cases
- Building a multi-tenant SaaS dashboard with HTTPS and auto-scaling - Deploy a frontend app, API backend, and database across three cloud VPS instances using a single docker-compose.yaml, with automatic TLS and DNS routing via Uncloud.
- Running a self-hosted e-commerce platform on bare metal and cloud VMs - Combine a local server with a $5/month VPS to host product images, order processing, and analytics—all with seamless failover and encrypted networking.
- Problem: Managing 5+ servers with Docker Compose is error-prone → Solution: Uncloud synchronizes state and deploys services uniformly across all nodes with one command - Instead of manually copying compose files and restarting containers, use
uc run to deploy and manage services cluster-wide.
- DevOps teams managing hybrid cloud environments - Use Uncloud to unify deployment workflows across AWS, Hetzner, and on-premises servers with consistent CLI commands and no Kubernetes YAML complexity.
Under The Hood
The project is a cloud-native orchestration system designed to manage and deploy applications across local and distributed environments with a focus on developer experience and self-hosted deployment. It integrates system-level operations, containerization, and distributed consensus to enable flexible cluster management.
Architecture
The system adopts a modular, layered architecture that clearly separates concerns between CLI, daemon, and core operational components. It supports both local and remote execution modes with defined control and data planes.
- The codebase is structured into internal modules that encapsulate distinct functionalities such as CLI handling, machine management, and network operations
- Service-oriented design is implemented through gRPC interfaces and middleware-style components for proxying and API handling
- Inter-component communication is managed via gRPC services and internal message passing protocols
- The architecture supports local-first development workflows while enabling seamless integration into distributed systems
Tech Stack
The project is built in Go with a strong emphasis on system-level tooling and infrastructure for managing containerized environments.
- Built in Go with extensive use of gRPC, WireGuard, Serf, and Corrosion for networking and consensus
- Relies on Docker and Talos for cluster and container management, with Makefiles and Go modules for build and dependency handling
- Integrates golangci-lint for linting and includes unit and integration tests with mocking support
- Emphasizes containerization via Docker and modular dependency management for scalable development
Code Quality
The codebase reflects a moderate level of quality with consistent Go idioms and structural organization, though some technical debt remains.
- Testing practices are comprehensive with extensive end-to-end test coverage in core modules like CLI and machine management
- Error handling follows standard Go patterns with error wrapping and propagation, though some areas could benefit from refined approaches
- Code consistency is generally strong with clear naming and modular structure, though duplicated logic and coupling exist in some areas
- The codebase demonstrates good use of type annotations and follows CI/CD practices with linting support
What Makes It Unique
The project introduces a distinctive blend of local-first development and distributed system primitives for managing cloud-native environments.
- Integrates low-level network control with container orchestration to support local simulation of multi-node clusters
- Leverages CRDTs and serf-based gossip protocols for decentralized state synchronization without centralized coordination
- Offers flexibility in deployment by supporting multiple container runtimes and OS-specific network configurations
- Prioritizes developer experience through CLI-driven workflows and embedded proxy mechanisms for service exposure