Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

feat(skills): add uncloud skill

David Parry8b6aed0b80e4
diff --git a/skills/uncloud/SKILL.md b/skills/uncloud/SKILL.md
new file mode 100644
index 000000000..405115c8d
--- /dev/null
+++ b/skills/uncloud/SKILL.md
@@ -0,0 +1,317 @@
+---
+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.
+
+## 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 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.
+
+---
+
+## 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 |