Skip to main content
Uncloud creates a flat WireGuard mesh network that connects all machines and containers. This network eliminates the need for complex networking setups and enables direct communication between any two containers, regardless of which machine they run on.

​
Network Architecture

Every Uncloud cluster uses a private 10.210.0.0/16 network range. Each machine gets a unique /24 subnet from this range:
CIDRDescription
10.210.0.0/16The entire WireGuard mesh network
10.210.X.0/24/24 subnet assigned to machine X
10.210.X.1/32Machine X address (first address in subnet)
10.210.X.Y/32Container Y address running on machine X
This flat design means containers can communicate directly without NAT or port forwarding. For example, a container at 10.210.0.5 on machine 0 can directly reach a container at 10.210.1.8 on machine 1.

​
IPv6 Management Network

In addition to the IPv4 container network, each machine gets an IPv6 management address. This address handles cluster control traffic like gRPC API calls and Corrosion database gossip. The management IP is deterministically derived from the machine’s WireGuard public key, ensuring each machine has a unique, predictable address.

​
WireGuard Configuration

Uncloud automatically configures a WireGuard interface named uncloud on each machine. The interface runs on UDP port 51820 and uses a 25-second keepalive interval to maintain connections through most firewalls. You can inspect the current WireGuard configuration on any machine: 
uc wg show
Example output: 
Machine name:         aws-east
WireGuard interface:  uncloud
WireGuard public key: qL8zVq5nQ2x3K9wR7mP1sT4cN6dE8fG2hJ5kL7oM9pA=
WireGuard port:       51820

PEER        PUBLIC KEY                                    ENDPOINT              HANDSHAKE       RECEIVED   SENT       ALLOWED IPS
aws-west    x9Y3zR2mK1nQ5vL8pT7dN4cE6fG2hJ5kL0oM9pA8bC=    203.0.113.42:51820    2m15s ago       45.2 MB    38.9 MB    10.210.1.0/24, fd00::1234:5678
hetzner-1   p7T4dN9cE2fG1hJ8kL5oM6pA3bC0xY9zR2mK1nQ5vL=    198.51.100.18:51820   1m33s ago       12.8 MB    15.3 MB    10.210.2.0/24, fd00::abcd:ef01
This shows:
  • The local machine’s WireGuard public key and port
  • Connected peers with their endpoints and connection health
  • Recent handshake times (healthy connections handshake every ~2 minutes)
  • Traffic statistics for each peer
  • Allowed IP ranges for routing

​
Peer Discovery

When you add a new machine to the cluster, Uncloud automatically distributes its WireGuard configuration to all existing machines. This happens through the Corrosion distributed database. The peer discovery mechanism is inspired by Talos Linux’s KubeSpan design. Here’s how it works:
  1. Initial connection: When you run uc machine add user@host, the CLI establishes an SSH connection to collect the machine’s public IP and WireGuard public key.
  2. State distribution: The new machine’s network configuration gets stored in Corrosion, which replicates it to all cluster machines via gossip protocol.
  3. WireGuard updates: Each machine watches for state changes and automatically updates its local WireGuard configuration to add new peers.
  4. Bidirectional connectivity: Once both machines have each other’s public keys and endpoints, they establish a direct WireGuard tunnel.
This design means you never manually configure WireGuard keys or endpoints. The cluster handles everything automatically.

​
NAT Traversal

Most machines sit behind NAT (Network Address Translation), which makes direct connections challenging. Uncloud handles this through several techniques:

​
Persistent Keepalive

Every WireGuard peer uses a 25-second persistent keepalive. This keeps the connection alive through stateful firewalls and creates reverse NAT mappings that allow incoming packets. The keepalive interval is carefully chosen to work with most consumer and enterprise firewalls while minimizing unnecessary traffic.

​
Endpoint Discovery

When a machine joins the cluster, Uncloud tries to determine its public endpoint:
  1. It collects all known IP addresses from the machine
  2. It prioritizes public IPs over private ones
  3. It uses port 51820 for all endpoints
If both machines are behind NAT, the persistent keepalive packets create reverse paths that allow bidirectional communication.

​
Connection Probing

Uncloud monitors the health of each WireGuard peer by tracking handshake times. If a peer shows no activity, it’s marked as “down” and the system rotates through alternative endpoints if available. The peer status calculation uses these timeouts:
  • 15 seconds: Initial connection timeout after endpoint change
  • 275 seconds: Established peer down interval (handshake timeout + rekey timeout)
You can see peer status in the uc wg show output through the “HANDSHAKE” column. A recent handshake (under 3 minutes) indicates a healthy connection.
If you’re running Uncloud on machines behind strict firewalls or carrier-grade NAT, you may need at least one machine with a public IP to act as a relay. The persistent keepalive helps maintain connections even through complex NAT scenarios.

​
Manual WireGuard Inspection

For deeper troubleshooting, you can use standard WireGuard tools on the machine itself: 
# Show WireGuard interface status
sudo wg show uncloud

# Show detailed peer information
sudo wg show uncloud peers

# Monitor real-time handshakes
watch -n 1 'sudo wg show uncloud latest-handshakes'

# Check interface configuration
ip addr show uncloud

# View routing table for WireGuard
ip route show dev uncloud
These commands run directly on the machine through SSH and show the raw WireGuard state.

​
Troubleshooting Connectivity

If containers can’t reach each other across machines, work through these checks:

​
1. Verify WireGuard Interface

uc wg show
Check that:
  • The interface is up and has the expected IP
  • All expected peers appear in the list
  • Handshake times are recent (under 5 minutes)

​
2. Test Machine-to-Machine Connectivity

From one machine, ping another machine’s IP: 
ping 10.210.1.1
If this fails, the WireGuard tunnel has an issue. Check that:
  • UDP port 51820 is accessible on the target machine
  • Firewall rules allow WireGuard traffic
  • The endpoint address is correct

​
3. Test Container-to-Container Connectivity

From inside a container, ping a container on another machine: 
uc exec <service-name> -- ping 10.210.1.5
If machine-to-machine works but container-to-container doesn’t:
  • Check that the Docker bridge network is using the correct subnet
  • Verify routing rules are in place for the peer subnets
  • Ensure IP forwarding is enabled on the machine

​
4. Check Firewall Rules

# On the machine via SSH
sudo iptables -L -v -n | grep 51820
You should see rules accepting UDP traffic on port 51820 from anywhere.

​
5. Review Daemon Logs

# On the machine via SSH
sudo journalctl -u uncloud -f
Look for messages about:
  • WireGuard interface creation
  • Peer configuration updates
  • Endpoint changes or rotation
  • Connection status changes
Never share your WireGuard private keys. The uc wg show command only displays public keys, but raw wg show output includes the private key. Be careful when sharing troubleshooting information.

​
Network Performance

WireGuard is extremely efficient. In most cases, the overhead is negligible:
  • Encryption: ChaCha20 for data, Poly1305 for authentication
  • Handshake: Noise protocol framework with modern cryptography
  • Throughput: Near line-rate on most hardware (multi-gigabit)
  • Latency: Typically adds less than 1ms
The flat mesh design means traffic between any two containers takes the shortest path. There’s no centralized routing or tunneling through a gateway.

​
Advanced Configuration

The WireGuard mesh is managed entirely by Uncloud. You don’t need to (and shouldn’t) manually edit WireGuard configuration files. If you need custom networking:
  • Use Docker networking features within compose files
  • Add firewall rules for specific container traffic
  • Set up external VPNs or tunnels in parallel with the Uncloud mesh
The Uncloud WireGuard network coexists peacefully with other networking configurations on the machine.

Build docs developers (and LLMs) love

Get started for freeTalk to us