uncloud

Uncloud replaces the traditional 'cluster' concept with a 'network' of machines. It uses a flat WireGuard mesh network to enable secure, direct communication between machines and containers without address translation.

Each machine is assigned a /24 subnet within the larger WireGuard mesh (e.g., 10.210.0.0/16). The machine itself uses a /32 address (the first address of its assigned subnet), while containers are assigned individual /32 addresses within that same /24 subnet. This allows containers to communicate across different hosts using their mesh IP addresses.

Uncloud operates on several core architectural principles:

• Decentralised Design: There is no centralized control plane or manager quorum. All machines in a cluster are equal, and you can connect to any machine to manage containers on any other machine in the cluster.
• Zero-config Overlay Network: Uses a secure WireGuard mesh network for peer discovery and NAT traversal. Containers on different machines receive unique IP addresses from the cluster network, allowing direct communication.
• Minimal Footprint: The Uncloud daemon (Go and Rust binaries) runs alongside Docker and typically requires less than 150 MB of RAM.
• Troubleshooting: Since Uncloud works alongside standard Docker, you can use standard tools like ping (using service names), curl, or wireshark to debug container traffic.

Uncloud utilizes Caddy as its reverse proxy to manage incoming traffic, provide automatic HTTPS via Let's Encrypt, and route requests to services.

By default, Caddy runs as a global service named caddy on every machine in the cluster, listening on the following host ports:

• 80 (HTTP)
• 443 (HTTPS)
• 443/UDP (HTTP/3)

Uncloud uses a decentralized orchestration model where every machine is equal and can act as a control plane. There is no single centralized controller.

To maintain consistency across the network, Uncloud uses:

• Shared State: The entire network state is stored on every machine.
• CRDTs (Conflict-Free Replicated Data Types): Used to allow machines to modify state independently and resolve conflicts automatically, ensuring eventual convergence.
• Gossip Protocol: Used to propagate state updates across the network (inspired by HashiCorp Serf).

This architecture prioritizes Availability and Partition tolerance (AP) in the CAP theorem, meaning the system remains functional even during network partitions.

To begin using Uncloud, you need to install the CLI and deploy an application. Follow these steps:

1. Install the Uncloud CLI: Refer to the Installation Guide.
2. Deploy a demo app: Follow the Demo Deployment Guide to see Uncloud in action.

Uncloud is designed to be used with imperative CLI commands that provide execution plans for changes (e.g., which containers or volumes will be created/removed) before they are applied.

To start a new cluster, use the uc machine init command. This command SSHs into the target machine to install Docker, the uncloudd machine daemon (managed via systemd), and the Uncloud uninstall script. It also sets up a unique WireGuard key pair and allocates a dedicated subnet (e.g., 10.210.0.0/24) for the machine and its containers. The machine's connection information is stored locally in ~/.config/uncloud/config.yaml.

$ uc machine init --name oracle-vm ubuntu@152.67.101.197

You can combine Go templates with Bash-like environment variable interpolation. Environment variables are expanded before the template is rendered.

Syntax:

• ${VAR}: Standard interpolation.
• ${VAR:-default}: Interpolation with a default value if VAR is not set.

# CI build number from environment
image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}.${GITHUB_RUN_ID}   # → myapp:20251030.84d33bb.1234

# With default value
image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}   # GITHUB_RUN_ID not set → myapp:84d33bb.local

Use the uc logs command to view logs from all replicas of specified services across all machines in the cluster.

If no services are specified, the command streams logs from all services defined in the Compose file (defaults to compose.yaml).

To target a specific container within a service, use the SERVICE/CONTAINER format, where CONTAINER is a container name, full ID, or unique ID prefix.

uc logs [SERVICE[/CONTAINER]...] [flags]

To expose services to the internet, you must run a reverse proxy (such as Traefik or Caddy) on one or more machines that have public IP addresses.

In the Uncloud design, you control which machines act as ingress points by assigning them an appropriate role. The reverse proxy should be configured to use the Uncloud internal DNS server for service discovery, allowing it to automatically find and route traffic to containers across the mesh network. This setup also supports automatic TLS via Let's Encrypt.