---

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/16 by default; DNS provided inside the mesh
• Caddyfile is autogenerated — never edit it directly; use x-caddy / --caddyfile instead

---

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