Uncloud
Operate a decentralized Uncloud cluster—deploy Compose services, publish ports, and tune Caddy ingress with the uc CLI.
Overview
Uncloud is an agent skill for the Operate phase that documents uc CLI workflows for decentralized Docker clusters, WireGuard mesh, and Caddy ingress.
Install
npx skills add https://github.com/affaan-m/everything-claude-code --skill uncloudWhat is this skill?
- uc CLI reference for machine init/join, deploy, scale, logs, volumes, and DNS
- Docker Compose deploy with Uncloud extensions (x-caddy, x-ports, --caddyfile)
- WireGuard mesh networking between peer machines with equal cluster members
- Publish HTTP, HTTPS, TCP, and UDP through cluster ingress
- Static proxy routes for external LAN devices via cluster Caddy
Adoption & trust: 696 installs on skills.sh; 210k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You run self-hosted services on multiple machines but lack a single agent-ready reference for Uncloud deploy, ingress, and cluster operations.
Who is it for?
Indie operators already committed to Uncloud who want Claude to emit correct uc and Compose patterns under pressure.
Skip if: Builders on managed PaaS-only workflows (Vercel/Fly without self-host) or teams not using Docker plus uc.
When should I use this skill?
Managing an Uncloud cluster—deploying services, Caddy ingress, static proxy routes, publishing ports, scaling, logs, machines, or volumes with uc.
What do I get? / Deliverables
You can bootstrap or join machines, deploy Compose with Uncloud extensions, publish ports, route LAN devices, and inspect logs and placement with uc commands.
- Correct uc command sequences and Compose ingress/placement configuration
- Documented port publish and proxy route setup for services
Recommended Skills
Journey fit
Operate is the canonical shelf because the skill documents day-two cluster life: machines, services, logs, volumes, DNS, and proxy routing—not initial product coding. Infra subphase matches self-hosted Docker across a WireGuard mesh with global Caddy termination and LAN static proxy routes.
How it compares
Infrastructure uc CLI reference for Uncloud—not a generic Docker Compose tutorial or Kubernetes skill.
Common Questions / FAQ
Who is uncloud for?
Solo builders and small teams self-hosting with Uncloud who need accurate uc CLI guidance for deploy, ingress, and cluster hygiene.
When should I use uncloud?
Use it in Operate when bootstrapping machines with uc machine, deploying from Compose, configuring Caddy via x-caddy or x-ports, publishing TCP/UDP, scaling services, or routing non-cluster LAN devices through the proxy.
Is uncloud safe to install?
Following uc commands changes live cluster state, networks, and exposed ports—review the Security Audits panel on this page and validate changes in non-production first.
SKILL.md
READMESKILL.md - 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 ```bash 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 ```bash 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 ```bash uc volume ls # All volumes uc volume ls -m machine1 # On specific machine uc volume create NAME -m MACHINE uc volume rm NAME ``` ### Caddy ```bash uc caddy config # Show current generated Caddyfile (read-only) uc caddy deploy # Deploy/upgrade Caddy across cluster ``` ### DNS & Context ```bash 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