AIPM
Theme

AIPM package

Uncloud

@affaan-m/uncloud@1.0.0

Configuring Caddy ingress, adding static proxy routes for non-cluster devices, publishing ports, scaling, inspecting logs, or managing machines and volumes w…

Scanned · no issues · Nov 7, 2026

GitHub stars: ★ 299K

LinkedInPost

Install Skill

Pins this version in aipm.package.json and aipm-lock.json.

aipm add @affaan-m/uncloud@1.0.0

Without project tracking

Writes the skill files only. Add --no-init to skip aipm.package.json and the lockfile.

aipm add @affaan-m/uncloud@1.0.0 --no-init

How to use

Install the skill above, then run this in your AI tool:

/uncloud <your description>

About

Reference for the `uc` CLI — a decentralised self-hosting platform using Docker containers, WireGuard mesh networking, and Caddy reverse proxy.

Source

What gets added to your project

Preview every file this package writes on install before you run the command above.

Summary

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.

Skill instructions

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)

code
-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)

code
-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

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

Loading package files…

Share this package

Add an Install with AIPM badge

Add this badge to a GitHub README so readers can open the package page and install the same version.

Install with AIPM
[![Install with AIPM](https://www.aipm-registry.com/install-with-aipm.svg)](https://www.aipm-registry.com/skills/affaan-m/uncloud/1.0.0?utm_source=github&utm_medium=readme&utm_campaign=package_badge)

Publisher

Affaan Mustafa

This imported publisher has not claimed its AIPM account. A connected account confirms account control, but it does not guarantee that a package is safe.

AI assistant context

What this skill is for

@affaan-m/uncloud@1.0.0 is an AIPM skill package for All tools. Use it when a project needs the reusable AI behavior described as: 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.

Install
aipm add @affaan-m/uncloud@1.0.0
Use after install
/uncloud <your description>

Tool targets

Install command by target

Add --no-init to any of these when you want the skill files without aipm.package.json or aipm-lock.json.

cursor

Run this variant when you want to install the package into cursor.

aipm add @affaan-m/uncloud@1.0.0 --target cursor --ci

claude

Run this variant when you want to install the package into claude.

aipm add @affaan-m/uncloud@1.0.0 --target claude --ci

Discussion

Comments (0)

Loading comments…

Keep exploring

Affaan Mustafa/ui-canvas

Preview a UI component mockup in a local browser canvas where the human directly edits it (move, resize, edit text, delete, restyle), switches mobile/desktop/custom viewports, tests it, chats with you, and clicks Save and Finish. You the...

Published by Affaan Mustafa

skillScanned · no issues★ 308KImported · UnverifiedAll toolsNov 21, 2026, 1:11 AM6.61 KBMIT

Affaan Mustafa/yoruba-localization-testing

Test Yoruba (yo) and English bilingual interfaces for tone marks, underdots, Unicode normalization, translation fallback, and accessibility.

Published by Affaan Mustafa

skillScanned · no issues★ 306KImported · UnverifiedAll toolsNov 18, 2026, 1:19 AM3.43 KBMIT

Affaan Mustafa/web-perimeter-owasp-2025-audit

Passive, non-destructive web perimeter security auditing mapped to OWASP Top 10:2025 surface leads, CDN Unkeyed Header Web Cache Poisoning (X-Forwarded-Host), supply chain manifest exposure, git object dumping prevention (/.git/HEAD), cr...

Published by Affaan Mustafa

skillScanned · flagged★ 305KImported · UnverifiedAll toolsNov 17, 2026, 1:13 AM8.86 KBMIT

Package FAQ

Install and compatibility

How to install
Run aipm add @affaan-m/uncloud@1.0.0 in a project that has AIPM initialized.
Supported tools
@affaan-m/uncloud@1.0.0 supports All tools.

Before installing

AIPM skills can add files to your project. Review the package name, target, description, license, and publisher before installing. Use a clean branch when trying a new skill.