Uncloud

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-1uc service run --name web -p app.example.com:8080/https nginx:latestuc 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

Key init flags: --name, --network 10.210.0.0/16, --no-caddy, --no-dns, --public-ip auto\|IP\|none

Services

Images

uc image push myapp:latest                    # Push local image to all machinesuc image push myapp:latest -m machine1,machine2  # Push to specific machinesuc images                                     # List images in cluster

Volumes

uc volume ls                  # All volumesuc volume ls -m machine1      # On specific machineuc volume create NAME -m MACHINEuc 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 domainuc dns reserve     # Reserve a new domainuc ctx ls          # List cluster contextsuc ctx use prod    # Switch context

Port Publishing

HTTP/HTTPS (via Caddy reverse proxy)

-p [hostname:]container_port[/protocol]

TCP/UDP (host-bound, bypasses Caddy)

-p [host_ip:]host_port:container_port[/protocol]@host

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 8000}} {          import common_proxy        }        basic_auth /admin/* {          admin $2a$14$...        }      }

Template functions available inside x-caddy:

• {{upstreams [service] [port]}} — healthy container IPs
• {{.Name}} — service name
• {{.Upstreams}} — map of all services → IPs

x-machines — placement constraints

services:  db:    image: postgres:18    x-machines: db-machine          # Single machine name  app:    image: app:latest    x-machines:      - machine-1      - machine-2

Full multi-service example

services:  api:    build: ./api    x-ports:      - api.example.com:3000/https    environment:      DATABASE_URL: postgres://db:5432/mydb
  web:    build: ./web    x-ports:      - example.com:8000/https      - www.example.com:8000/https    environment:      API_URL: http://api:3000
  db:    image: postgres:18    environment:      POSTGRES_PASSWORD: ${DB_PASSWORD}    volumes:      - db-data:/var/lib/postgresql/data    x-machines: db-machine
volumes:  db-data:

Routing to External (Non-Cluster) Devices

To expose an external device (e.g. BMC, NAS, router UI) via Caddy without running a real container:

1. Create a Caddyfile snippet (e.g. ~/device.caddyfile):

https://device.example.com {    reverse_proxy https://192.168.1.x {        transport http {            tls_insecure_skip_verify   # needed for self-signed BMC certs        }    }    log}

For plaintext upstream: reverse_proxy http://192.168.1.x:port

2. Register as a named service with no-op container:

uc service run \  --name device-bmc \  --caddyfile ~/device.caddyfile \  registry.k8s.io/pause:3.9

pause is a minimal no-op container — it does nothing, but gives Uncloud a service entry to attach the Caddyfile to.

3. Verify:

uc caddy config   # device.example.com block should appear

--caddyfile cannot be combined with non-@host published ports.

DNS tip: A wildcard record (*.yourdomain.com → cluster-public-ip) means any new subdomain works immediately — no DNS change needed per service.

Service DNS (Internal)

Services inside the cluster resolve each other by name:

Scaling & Global Services

uc scale web 5    # 5 replicas (spread across machines)uc scale web 1    # Scale down

services:  caddy:    deploy:      mode: global   # One container on every machine

Image Tag Templates (in compose.yaml)

image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}

Common Workflows

Deploy from source:

uc deploy                          # Build + push + deployuc build --push && uc deploy --no-build   # Separate steps

Inspect a service:

uc inspect webuc logs -f webuc logs --since 1h webuc exec web                        # Opens shelluc exec web /bin/sh -c "env"       # Run specific command

Zero-downtime deploys happen automatically; Uncloud waits for health checks before terminating old containers.

Force recreate:

uc deploy --recreate

Common Mistakes