Uncloud — Lightweight Container Orchestration Across Docker Hosts

Introduction

Uncloud is a lightweight container orchestration tool that lets you deploy applications across multiple Docker hosts without the operational overhead of Kubernetes. It provides a simple CLI for managing distributed containers, handling networking, load balancing, and service discovery across a cluster of machines connected via WireGuard.

What Uncloud Does

• Deploys containers across multiple Docker hosts from a single CLI
• Creates an encrypted WireGuard mesh network between cluster nodes automatically
• Provides built-in load balancing and service discovery for deployed applications
• Supports rolling updates and health checks for zero-downtime deployments
• Manages TLS certificates automatically for exposed services

Architecture Overview

Uncloud runs a lightweight agent on each Docker host in the cluster. Nodes communicate over a WireGuard mesh network that Uncloud provisions automatically. The CLI sends deployment commands to any node, which schedules containers across the cluster based on available resources. A built-in DNS server handles service discovery, and an integrated reverse proxy routes external traffic to the correct containers. All cluster state is stored in an embedded distributed database.

Self-Hosting & Configuration

• Install the Uncloud binary on each host via the official install script
• Run uncloud init on the first node to create the cluster and generate a join token
• Join additional nodes using uncloud join <token>
• Deploy applications with uncloud deploy specifying image, ports, and replicas
• Configure custom domains and TLS settings for public-facing services

Key Features

• Zero-config WireGuard networking between cluster nodes
• Single binary with no external dependencies (no etcd, no separate database)
• Docker Compose-like simplicity for multi-host deployments
• Built-in reverse proxy with automatic TLS via Let's Encrypt
• Resource-aware scheduling across heterogeneous machines

Comparison with Similar Tools

• Kubernetes — Full orchestration platform with steep learning curve; Uncloud targets small-to-medium deployments with minimal setup
• Docker Swarm — Docker's built-in orchestration (deprecated features); Uncloud offers WireGuard networking and simpler UX
• Nomad — HashiCorp's workload orchestrator; Uncloud is lighter with fewer moving parts
• Kamal — Deploy Rails apps via SSH; Uncloud provides a persistent cluster with networking and service discovery

FAQ

Q: How many nodes can Uncloud handle? A: Uncloud is designed for small-to-medium clusters, typically 2-50 nodes. It trades the complexity of large-scale orchestrators for operational simplicity.

Q: Does Uncloud replace Docker Compose? A: Uncloud extends Docker Compose concepts to multiple hosts. You can think of it as Docker Compose with built-in clustering, networking, and load balancing.

Q: Is WireGuard required? A: WireGuard is used automatically for encrypted inter-node communication. Uncloud provisions and manages the WireGuard tunnels — no manual VPN setup needed.

Q: Can I use my existing Docker images? A: Yes. Uncloud deploys standard OCI/Docker images from any registry. No changes to your images or Dockerfiles are needed.

Sources

• https://github.com/psviderski/uncloud
• https://uncloud.run