
About
Use when managing an Uncloud cluster — deploying services, configuring Caddy ingress, adding static proxy routes for non-cluster devices, publishing ports, scaling, inspecting logs, or managing machines and volumes with the `uc` CLI.
name: uncloud
description: Use when managing an Uncloud cluster — deploying services, configuring Caddy ingress, adding static proxy routes for non-cluster devices, publishing ports, scaling, inspecting logs, or managing machines and volumes with the uc CLI.
origin: ECC
Uncloud Cluster Management
Reference for the uc CLI — a decentralised self-hosting platform using Docker containers, WireGuard mesh networking, and Caddy reverse proxy.
When to Activate
Use this skill when working with Uncloud clusters, especially when:
- Bootstrapping or joining machines with
uc machine - Deploying services from Compose files with
uc deploy - Publishing HTTP, HTTPS, TCP, or UDP ports through Uncloud
- Configuring Caddy ingress with
x-caddy,x-ports, or--caddyfile - Routing external LAN devices through the cluster proxy
- Inspecting logs, service state, volumes, DNS, or machine placement
How It Works
Uncloud runs Docker services across peer machines connected by a WireGuard mesh. Each machine is an equal cluster member; services communicate on the overlay network and Caddy runs globally to terminate public HTTP/HTTPS traffic. Compose files can use Uncloud extensions for ingress, placement, and generated Caddy configuration, while the uc CLI handles image distribution, scheduling, scaling, logs, and cluster state.
Examples
uc machine init user@host --name machine-1
uc service run --name web -p app.example.com:8080/https nginx:latest
uc deploy
Core Concepts
- No central control plane — all machines are equal peers connected by WireGuard
- Caddy runs as a global service on every machine; auto-obtains TLS from Let's Encrypt
- Overlay network — services communicate via
10.210.0.0/16by default; DNS provided inside the mesh - Caddyfile is autogenerated — never edit it directly; use
x-caddy/--caddyfileinstead
CLI Quick Reference
Machines
| Command | Purpose |
|---------|---------|
| uc machine init user@host | Bootstrap first machine / new cluster |
| uc machine add user@host | Join machine to existing cluster |
| uc machine ls | List machines |
| uc machine update NAME --public-ip IP | Update public IP for ingress |
| uc machine rm NAME | Remove machine |
Key init flags: --name, --network 10.210.0.0/16, --no-caddy, --no-dns, --public-ip auto\|IP\|none
Services
| Command | Purpose |
|---------|---------|
| uc service ls / uc ls | List services |
| uc service run IMAGE | Run a single container service |
| uc deploy | Deploy from compose.yaml |
| uc deploy --no-build | Deploy already-pushed images without rebuilding |
| uc deploy --recreate | Force service recreation |
| uc scale SERVICE N | Set replica count |
| uc service logs SERVICE | View logs |
| uc service exec SERVICE | Shell into container |
| uc service inspect SERVICE | Detailed info |
| uc service rm SERVICE | Remove service (keeps named volumes) |
| uc ps | All containers across cluster |
Images
uc image push myapp:latest # Push local image to all machines
uc image push myapp:latest -m machine1,machine2 # Push to specific machines
uc images # List images in cluster
Volumes
uc volume ls # All volumes
uc volume ls -m machine1 # On specific machine
uc volume create NAME -m MACHINE
uc volume rm NAME
Caddy
uc caddy config # Show current generated Caddyfile (read-only)
uc caddy deploy # Deploy/upgrade Caddy across cluster
DNS & Context
uc dns show # Show reserved *.uncld.dev domain
uc dns reserve # Reserve a new domain
uc ctx ls # List cluster contexts
uc ctx use prod # Switch context
Port Publishing
HTTP/HTTPS (via Caddy reverse proxy)
-p [hostname:]container_port[/protocol]
| Example | Meaning |
|---------|---------|
| -p 8080/https | HTTPS with auto service-name.cluster-domain hostname |
| -p app.example.com:8080/https | HTTPS with custom hostname |
| -p 8080/http | HTTP only, no TLS |
TCP/UDP (host-bound, bypasses Caddy)
-p [host_ip:]host_port:container_port[/protocol]@host
| Example | Meaning |
|---------|---------|
| -p 5432:5432@host | TCP 5432 on all interfaces |
| -p 127.0.0.1:5432:5432@host | TCP 5432 loopback only |
| -p 53:5353/udp@host | UDP |
Compose File Extensions
Uncloud adds these extensions on top of Docker Compose:
x-ports — publish ports with domains
services:
app:
image: app:latest
x-ports:
- example.com:8000/https
- www.example.com:8000/https
- api.example.com:9000/https
x-caddy — custom Caddy config for service
services:
app:
image: app:latest
x-caddy: |
example.com {
redir https://www.example.com{uri} permanent
}
www.example.com {
reverse_proxy {{upstreams

