Uncloud
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.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Uncloud when an AI agent needs a reusable SKILL.md workflow for this job: 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.
When not to use it
Skip Uncloud when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/uncloud # Save SKILL.md to ~/.claude/skills/uncloud/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/uncloud/SKILL.md. For a shared project, commit the folder at .claude/skills/uncloud/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Uncloud skill for this task: Use Uncloud when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 70/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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 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
```yaml 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
```yaml 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
```yaml 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
```yaml 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`):
```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:**
```bash 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:**
```bash 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:
| DNS name | Resolves to | |----------|------------| | `service-name` | Any healthy container | | `service-name.internal` | Same | | `rr.service-name.internal` | Round-robin | | `nearest.service-name.internal` | Machine-local first |
---
## Scaling & Global Services
```bash uc scale web 5 # 5 replicas (spread across machines) uc scale web 1 # Scale down ```
```yaml services: caddy: deploy: mode: global # One container on every machine ```
---
## Image Tag Templates (in compose.yaml)
```yaml image: myapp:{{gitdate "20060102"}}.{{gitsha 7}} image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local} ```
| Function | Output | |----------|--------| | `{{gitsha N}}` | First N chars of commit SHA | | `{{gitdate "format"}}` | Git commit date in Go format | | `{{date "format"}}` | Current date |
---
## Common Workflows
**Deploy from source:** ```bash uc deploy # Build + push + deploy uc build --push && uc deploy --no-build # Separate steps ```
**Inspect a service:** ```bash uc inspect web uc logs -f web uc logs --since 1h web uc exec web # Opens shell uc 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:** ```bash uc deploy --recreate ```
---
## Common Mistakes
| Mistake | Fix | |---------|-----| | Editing the Caddyfile directly | Use `x-caddy` in compose or `--caddyfile` on `uc service run` | | Proxying an HTTPS upstream with self-signed cert | Add `transport http { tls_insecure_skip_verify }` | | `uc caddy config` shows no user-defined blocks | Caddy admin socket unreachable — check `uc inspect caddy` and `uc logs caddy` | | Service can't reach external LAN IP from container | Verify Caddy container's host can route to target network | | Volumes lost after `uc service rm` | Named volumes persist; only anonymous volumes are auto-removed |
Intended uses
- Use Uncloud when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.