Agent skill

Uncloud

by affaan-m in affaan-m/ECC

A skill your agent uses when managing an Uncloud cluster — deploying services, configuring Caddy ingress, adding static proxy routes for non-cluster devices, publishing ports, scaling, inspecting…

MITAuto-check passedDevOps & Cloud

Install Uncloud

skills CLI
$ npx skills add affaan-m/ECC --skill uncloud -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install affaan-m/ECC uncloud --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/affaan-m/ECC.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/uncloud .claude/skills/uncloud && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
uncloud
GitHub stars
276k
Used in
1 other repo
Token cost
~2.3k tokens
SKILL.md length
690 words
Files
1
Skills in repo
683
Repo updated
First seen
Licence
MIT

At a glance

A skill your agent uses when managing an Uncloud cluster — deploying services, configuring Caddy ingress, adding static proxy routes for non-cluster devices, publishing ports, scaling, inspecting…

  • Managing an Uncloud cluster — deploying services
  • SKILL.md covers When to Activate, How It Works, Examples and Core Concepts, plus 9 more sections
  • Needs POSTGRES_PASSWORD and DB_PASSWORD
  • Configuring Caddy ingress

What it does

Uncloud is an agent skill from affaan-m/ECC. 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.

Its SKILL.md is about 2.3k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in DevOps & Cloud, covering Cloud networking. The repository describes itself as: The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond. The licence is MIT.

When your agent uses it

  • Managing an Uncloud cluster — deploying services
  • Configuring Caddy ingress
  • Adding static proxy routes for non-cluster devices
  • Publishing ports

Example prompts

  • “/uncloud”

Requirements

  • Docker

What it can do on your machine

Read from SKILL.md and the folder at commit 4eb71d9. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are bash, yaml and caddyfile).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • POSTGRES_PASSWORD
    • DB_PASSWORD

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Uncloud loads about 2.3k tokens when it runs. Until then it costs about 60 tokens; SKILL.md has 690 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~60
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from affaan-m/ECC at commit 4eb71d9, republished under its MIT licence (© affaan-m). 690 words, ~2,313 tokens.

Download SKILL.mdSave it as .claude/skills/uncloud/SKILL.md (or your agent's skills folder).
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.
metadata.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

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
CommandPurpose
uc machine init user@hostBootstrap first machine / new cluster
uc machine add user@hostJoin machine to existing cluster
uc machine lsList machines
uc machine update NAME --public-ip IPUpdate public IP for ingress
uc machine rm NAMERemove machine

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

Services
CommandPurpose
uc service ls / uc lsList services
uc service run IMAGERun a single container service
uc deployDeploy from compose.yaml
uc deploy --no-buildDeploy already-pushed images without rebuilding
uc deploy --recreateForce service recreation
uc scale SERVICE NSet replica count
uc service logs SERVICEView logs
uc service exec SERVICEShell into container
uc service inspect SERVICEDetailed info
uc service rm SERVICERemove service (keeps named volumes)
uc psAll 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]
ExampleMeaning
-p 8080/httpsHTTPS with auto service-name.cluster-domain hostname
-p app.example.com:8080/httpsHTTPS with custom hostname
-p 8080/httpHTTP only, no TLS
TCP/UDP (host-bound, bypasses Caddy)
-p [host_ip:]host_port:container_port[/protocol]@host
ExampleMeaning
-p 5432:5432@hostTCP 5432 on all interfaces
-p 127.0.0.1:5432:5432@hostTCP 5432 loopback only
-p 53:5353/udp@hostUDP

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
Show full SKILL.md (283 more words)Show less
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 nameResolves to
service-nameAny healthy container
service-name.internalSame
rr.service-name.internalRound-robin
nearest.service-name.internalMachine-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}
FunctionOutput
{{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

MistakeFix
Editing the Caddyfile directlyUse x-caddy in compose or --caddyfile on uc service run
Proxying an HTTPS upstream with self-signed certAdd transport http { tls_insecure_skip_verify }
uc caddy config shows no user-defined blocksCaddy admin socket unreachable — check uc inspect caddy and uc logs caddy
Service can't reach external LAN IP from containerVerify Caddy container's host can route to target network
Volumes lost after uc service rmNamed volumes persist; only anonymous volumes are auto-removed

© affaan-m, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/uncloud of affaan-m/ECC.

Open the folder on GitHubat commit 4eb71d9

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in affaan-m/ECC, which our catalogue first saw on October 9, 2026.

Compare with similar skills

Uncloud next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Uncloud compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Uncloud this skillaffaan-m/ECC276k1 repos~2.3kAutomated safety check: PassMIT
Kubeshark KFL2 Filter Referencekubeshark/kubeshark12k—~3.6kAutomated safety check: PassApache-2.0
Nginx To Higress Migrationhigress-group/higress9.5k—~3.9kAutomated safety check: PassApache-2.0
Bfe Rd Workflowbfenetworks/bfe6.3k—~1.3kAutomated safety check: PassApache-2.0
NGINX Ingress Controller Feature Checklistsnginx/kubernetes-ingress5.1k—~1.4kAutomated safety check: PassApache-2.0
NGINX Ingress Policy CRD Guidenginx/kubernetes-ingress5.1k—~2kAutomated safety check: PassApache-2.0

Similar skills

  • Syntax reference for KFL2, the CEL-based display filter language used to search Kubernetes network traffic captured by Kubeshark, loaded before any filter is written.

    12k GitHub stars~3.6k tokensUpdated today
    DevOps & CloudAuto-check passed
  • Nginx To Higress Migration

    higress-group/higress

    Migrate from ingress-nginx to Higress in Kubernetes environments.

    9.5k GitHub stars~3.9k tokensUpdated 2 days ago
    DevOps & CloudAuto-check passed
  • Bfe Rd Workflow

    bfenetworks/bfe

    引导用户在 bfe 代码库中完成一次完整的功能研发流程,包括需求对齐、文档修改、代码实现、集成测试与回归验证. An agent skill from bfenetworks/bfe.

    6.3k GitHub stars~1.3k tokensUpdated today
    DevOps & CloudAuto-check passed
  • Gives step-by-step checklists for adding Ingress annotations, VirtualServer fields and Helm values to the NGINX Kubernetes Ingress Controller, with common gotchas.

    5.1k GitHub stars~1.4k tokensUpdated today
    DevOps & CloudAuto-check passed
  • NGINX Ingress Policy CRD Guide

    nginx/kubernetes-ingress

    Step-by-step checklist for adding a new Policy CRD type to the NGINX Ingress Controller, from the Go types and validation to config generation and templates.

    5.1k GitHub stars~2k tokensUpdated today
    DevOps & CloudAuto-check passed
  • ArvanCloud API Operator

    erfnzdeh/arvancloud-agent-skill

    Drives ArvanCloud's REST APIs for CDN, DNS, cloud servers, object storage and more, with helper scripts for calls, account inventory and certificates.

    134 GitHub stars~3.9k tokensUpdated 12 days ago
    DevOps & CloudAuto-check passed

More from affaan-m/ECC

All 683 skills in this repo
  • Skill Stocktake

    affaan-m/ECC

    Audits your installed Claude skills and commands for quality, with a quick mode for recently changed skills and a full mode that evaluates all of them through subagents.

    276k GitHub starsUsed in 5 repos~3.1k tokens
    Auto-check passed
  • Ingests, indexes, searches, edits and monitors video, audio and live streams through the VideoDB Python SDK, returning stream links, clips and timestamps.

    276k GitHub starsUsed in 3 repos~3.5k tokens
    Auto-check: notes
  • Docs Governance

    affaan-m/ECC

    Route broad documentation-governance requests to existing ECC skills and run an opt-in, read-only audit of mapped documentation roles, links, ADR indexes, and evidence references.

    276k GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • Rules Distillation

    affaan-m/ECC

    Scans installed skills for principles that recur across them and proposes rule-file changes: append, revise, add a section, create a file or leave as covered.

    276k GitHub starsUsed in 2 repos~2.3k tokens
    Auto-check passed
  • Builds DRAFT counterparty agreements from one markdown template and a small JSON spec per party, with clauses picked by the party's role.

    276k GitHub stars~2.9k tokensUpdated today
    Auto-check passed
  • Measures whether agents actually follow a skill, rule or agent definition by generating scenarios at three strictness levels and scoring tool-call traces.

    276k GitHub starsUsed in 1 repo~623 tokens
    Auto-check passed

Categories

Questions about Uncloud

What does Uncloud do?

A skill your agent uses when managing an Uncloud cluster — deploying services, configuring Caddy ingress, adding static proxy routes for non-cluster devices, publishing ports, scaling, inspecting…. Uncloud is an agent skill from affaan-m/ECC. 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 should I use Uncloud?

Uncloud fits situations like: managing an Uncloud cluster — deploying services; configuring Caddy ingress; adding static proxy routes for non-cluster devices; publishing ports.

How do I install Uncloud in Claude Code?

Run `npx skills add affaan-m/ECC --skill uncloud -a claude-code`. Or copy the skill folder (skills/uncloud in affaan-m/ECC) into .claude/skills/uncloud in your project. Claude Code loads it when a task matches its description.

How do I install Uncloud in Codex?

Run `npx skills add affaan-m/ECC --skill uncloud -a codex`. Or copy the skill folder (skills/uncloud in affaan-m/ECC) into .agents/skills/uncloud in your project. Codex loads it when a task matches its description.

Can I use Uncloud in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add affaan-m/ECC --skill uncloud -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/uncloud, .gemini/skills/uncloud, .github/skills/uncloud and .opencode/skills/uncloud in your project.

What does Uncloud need to run?

Going by SKILL.md and its folder, Uncloud needs credentials named POSTGRES_PASSWORD and DB_PASSWORD. Our summary lists: Docker.

Does Uncloud access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Uncloud safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Uncloud use?

Uncloud is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Uncloud use?

About 2.3k tokens (SKILL.md is roughly 9.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Uncloud?

Skills that share tags, products or a category with Uncloud: Kubeshark KFL2 Filter Reference (kubeshark/kubeshark, 12k stars), Nginx To Higress Migration (higress-group/higress, 9.5k stars), Bfe Rd Workflow (bfenetworks/bfe, 6.3k stars) and NGINX Ingress Controller Feature Checklists (nginx/kubernetes-ingress, 5.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Uncloud?

affaan-m (a GitHub user) maintains it in affaan-m/ECC, which has 276,111 GitHub stars. The repository holds 683 skills in this directory. The repository was last updated on October 10, 2026.

Source: affaan-m/ECC on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.