calvyn-code 0.14.0

package/optional-skills/devops/docker-management/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: docker-management
+description: Manage Docker containers, images, volumes, networks, and Compose stacks — lifecycle ops, debugging, cleanup, and Dockerfile optimization.
+version: 1.0.0
+author: sprmn24
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [docker, containers, devops, infrastructure, compose, images, volumes, networks, debugging]
+    category: devops
+    requires_toolsets: [terminal]
+---
+
+# Docker Management
+
+Manage Docker containers, images, volumes, networks, and Compose stacks using standard Docker CLI commands. No additional dependencies beyond Docker itself.
+
+## When to Use
+
+- Run, stop, restart, remove, or inspect containers
+- Build, pull, push, tag, or clean up Docker images
+- Work with Docker Compose (multi-service stacks)
+- Manage volumes or networks
+- Debug a crashing container or analyze logs
+- Check Docker disk usage or free up space
+- Review or optimize a Dockerfile
+
+## Prerequisites
+
+- Docker Engine installed and running
+- User added to the `docker` group (or use `sudo`)
+- Docker Compose v2 (included with modern Docker installations)
+
+Quick check:
+
+```bash
+docker --version && docker compose version
+```
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Run container (background) | `docker run -d --name NAME IMAGE` |
+| Stop + remove | `docker stop NAME && docker rm NAME` |
+| View logs (follow) | `docker logs --tail 50 -f NAME` |
+| Shell into container | `docker exec -it NAME /bin/sh` |
+| List all containers | `docker ps -a` |
+| Build image | `docker build -t TAG .` |
+| Compose up | `docker compose up -d` |
+| Compose down | `docker compose down` |
+| Disk usage | `docker system df` |
+| Cleanup dangling | `docker image prune && docker container prune` |
+
+## Procedure
+
+### 1. Identify the domain
+
+Figure out which area the request falls into:
+
+- **Container lifecycle** → run, stop, start, restart, rm, pause/unpause
+- **Container interaction** → exec, cp, logs, inspect, stats
+- **Image management** → build, pull, push, tag, rmi, save/load
+- **Docker Compose** → up, down, ps, logs, exec, build, config
+- **Volumes & networks** → create, inspect, rm, prune, connect
+- **Troubleshooting** → log analysis, exit codes, resource issues
+
+### 2. Container operations
+
+**Run a new container:**
+
+```bash
+# Detached service with port mapping
+docker run -d --name web -p 8080:80 nginx
+
+# With environment variables
+docker run -d -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=mydb --name db postgres:16
+
+# With persistent data (named volume)
+docker run -d -v pgdata:/var/lib/postgresql/data --name db postgres:16
+
+# For development (bind mount source code)
+docker run -d -v $(pwd)/src:/app/src -p 3000:3000 --name dev my-app
+
+# Interactive debugging (auto-remove on exit)
+docker run -it --rm ubuntu:22.04 /bin/bash
+
+# With resource limits and restart policy
+docker run -d --memory=512m --cpus=1.5 --restart=unless-stopped --name app my-app
+```
+
+Key flags: `-d` detached, `-it` interactive+tty, `--rm` auto-remove, `-p` port (host:container), `-e` env var, `-v` volume, `--name` name, `--restart` restart policy.
+
+**Manage running containers:**
+
+```bash
+docker ps                        # running containers
+docker ps -a                     # all (including stopped)
+docker stop NAME                 # graceful stop
+docker start NAME                # start stopped container
+docker restart NAME              # stop + start
+docker rm NAME                   # remove stopped container
+docker rm -f NAME                # force remove running container
+docker container prune           # remove ALL stopped containers
+```
+
+**Interact with containers:**
+
+```bash
+docker exec -it NAME /bin/sh          # shell access (use /bin/bash if available)
+docker exec NAME env                   # view environment variables
+docker exec -u root NAME apt update    # run as specific user
+docker logs --tail 100 -f NAME         # follow last 100 lines
+docker logs --since 2h NAME            # logs from last 2 hours
+docker cp NAME:/path/file ./local      # copy file from container
+docker cp ./file NAME:/path/           # copy file to container
+docker inspect NAME                    # full container details (JSON)
+docker stats --no-stream               # resource usage snapshot
+docker top NAME                        # running processes
+```
+
+### 3. Image management
+
+```bash
+# Build
+docker build -t my-app:latest .
+docker build -t my-app:prod -f Dockerfile.prod .
+docker build --no-cache -t my-app .              # clean rebuild
+DOCKER_BUILDKIT=1 docker build -t my-app .       # faster with BuildKit
+
+# Pull and push
+docker pull node:20-alpine
+docker login ghcr.io
+docker tag my-app:latest registry/my-app:v1.0
+docker push registry/my-app:v1.0
+
+# Inspect
+docker images                          # list local images
+docker history IMAGE                   # see layers
+docker inspect IMAGE                   # full details
+
+# Cleanup
+docker image prune                     # remove dangling (untagged) images
+docker image prune -a                  # remove ALL unused images (careful!)
+docker image prune -a --filter "until=168h"   # unused images older than 7 days
+```
+
+### 4. Docker Compose
+
+```bash
+# Start/stop
+docker compose up -d                   # start all services detached
+docker compose up -d --build           # rebuild images before starting
+docker compose down                    # stop and remove containers
+docker compose down -v                 # also remove volumes (DESTROYS DATA)
+
+# Monitoring
+docker compose ps                      # list services
+docker compose logs -f api             # follow logs for specific service
+docker compose logs --tail 50          # last 50 lines all services
+
+# Interaction
+docker compose exec api /bin/sh        # shell into running service
+docker compose run --rm api npm test   # one-off command (new container)
+docker compose restart api             # restart specific service
+
+# Validation
+docker compose config                  # validate and view resolved config
+```
+
+**Minimal compose.yml example:**
+
+```yaml
+services:
+  api:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - DATABASE_URL=postgres://user:pass@db:5432/mydb
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: pass
+      POSTGRES_DB: mydb
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U user"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  pgdata:
+```
+
+### 5. Volumes and networks
+
+```bash
+# Volumes
+docker volume ls                       # list volumes
+docker volume create mydata            # create named volume
+docker volume inspect mydata           # details (mount point, etc.)
+docker volume rm mydata                # remove (fails if in use)
+docker volume prune                    # remove unused volumes
+
+# Networks
+docker network ls                      # list networks
+docker network create mynet            # create bridge network
+docker network inspect mynet           # details (connected containers)
+docker network connect mynet NAME      # attach container to network
+docker network disconnect mynet NAME   # detach container
+docker network rm mynet                # remove network
+docker network prune                   # remove unused networks
+```
+
+### 6. Disk usage and cleanup
+
+Always start with a diagnostic before cleaning:
+
+```bash
+# Check what's using space
+docker system df                       # summary
+docker system df -v                    # detailed breakdown
+
+# Targeted cleanup (safe)
+docker container prune                 # stopped containers
+docker image prune                     # dangling images
+docker volume prune                    # unused volumes
+docker network prune                   # unused networks
+
+# Aggressive cleanup (confirm with user first!)
+docker system prune                    # containers + images + networks
+docker system prune -a                 # also unused images
+docker system prune -a --volumes       # EVERYTHING — named volumes too
+```
+
+**Warning:** Never run `docker system prune -a --volumes` without confirming with the user. This removes named volumes with potentially important data.
+
+## Pitfalls
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Container exits immediately | Main process finished or crashed | Check `docker logs NAME`, try `docker run -it --entrypoint /bin/sh IMAGE` |
+| "port is already allocated" | Another process using that port | `docker ps` or `lsof -i :PORT` to find it |
+| "no space left on device" | Docker disk full | `docker system df` then targeted prune |
+| Can't connect to container | App binds to 127.0.0.1 inside container | App must bind to `0.0.0.0`, check `-p` mapping |
+| Permission denied on volume | UID/GID mismatch host vs container | Use `--user $(id -u):$(id -g)` or fix permissions |
+| Compose services can't reach each other | Wrong network or service name | Services use service name as hostname, check `docker compose config` |
+| Build cache not working | Layer order wrong in Dockerfile | Put rarely-changing layers first (deps before source code) |
+| Image too large | No multi-stage build, no .dockerignore | Use multi-stage builds, add `.dockerignore` |
+
+## Verification
+
+After any Docker operation, verify the result:
+
+- **Container started?** → `docker ps` (check status is "Up")
+- **Logs clean?** → `docker logs --tail 20 NAME` (no errors)
+- **Port accessible?** → `curl -s http://localhost:PORT` or `docker port NAME`
+- **Image built?** → `docker images | grep TAG`
+- **Compose stack healthy?** → `docker compose ps` (all services "running" or "healthy")
+- **Disk freed?** → `docker system df` (compare before/after)
+
+## Dockerfile Optimization Tips
+
+When reviewing or creating a Dockerfile, suggest these improvements:
+
+1. **Multi-stage builds** — separate build environment from runtime to reduce final image size
+2. **Layer ordering** — put dependencies before source code so changes don't invalidate cached layers
+3. **Combine RUN commands** — fewer layers, smaller image
+4. **Use .dockerignore** — exclude `node_modules`, `.git`, `__pycache__`, etc.
+5. **Pin base image versions** — `node:20-alpine` not `node:latest`
+6. **Run as non-root** — add `USER` instruction for security
+7. **Use slim/alpine bases** — `python:3.12-slim` not `python:3.12`

package/optional-skills/devops/pinggy-tunnel/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: pinggy-tunnel
+description: Zero-install localhost tunnels over SSH via Pinggy.
+version: 0.1.0
+author: Teknium (teknium1), Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [Pinggy, Tunnel, Networking, SSH, Webhook, Localhost]
+    related_skills: [cloudflared-quick-tunnel, webhook-subscriptions]
+---
+
+# Pinggy Tunnel Skill
+
+Expose a local service (dev server, webhook receiver, MCP endpoint, demo) to the public internet using a Pinggy SSH reverse tunnel. No daemon to install — the user's stock SSH client connects to `a.pinggy.io:443` and Pinggy hands back a public HTTP/HTTPS URL.
+
+Free tier: 60-minute tunnels, random subdomain, no signup. Pro tier ($3/mo) is an opt-in with a token.
+
+## When to Use
+
+- User asks to "expose this locally", "share my dev server", "make this URL public", "tunnel port N", "get a public URL for a webhook"
+- Need to receive a webhook callback during a local task (Stripe, GitHub, Discord, AgentMail)
+- Sharing a one-off HTTP demo (MCP server, Ollama/vLLM endpoint, dashboard) with a remote party
+- The host has SSH but no `cloudflared` / `ngrok` binary, and installing one would be overkill
+
+If the host already has `cloudflared` configured, prefer the `cloudflared-quick-tunnel` skill — Cloudflare quick tunnels don't expire after 60 minutes.
+
+## Prerequisites
+
+- `ssh` on PATH (`ssh -V`). Default on Linux, macOS, and Windows 10+. No other install.
+- A local service listening on `127.0.0.1:<port>` before the tunnel starts. Pinggy will return URLs but they'll 502 until the local origin is up.
+
+Optional:
+
+- `PINGGY_TOKEN` env var for paid Pro features (persistent subdomain, custom domain, multiple tunnels, no 60-minute cap). Free tier needs no credentials.
+
+## Quick Reference
+
+```bash
+# Plain HTTP/HTTPS tunnel for port 8000 (free tier)
+ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 \
+    -R0:localhost:8000 free@a.pinggy.io
+
+# TCP tunnel (databases, raw SSH, etc.)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:5432 tcp@a.pinggy.io
+
+# TLS tunnel (Pinggy can't decrypt — bring your own certs at origin)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:443 tls@a.pinggy.io
+
+# Basic auth gate (b:user:pass)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "b:admin:secret+free@a.pinggy.io"
+
+# Bearer token gate (k:token)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "k:mysecrettoken+free@a.pinggy.io"
+
+# IP whitelist (w:CIDR)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "w:203.0.113.0/24+free@a.pinggy.io"
+
+# Enable CORS + force HTTPS redirect
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "co+x:https+free@a.pinggy.io"
+
+# Pro tier (persistent URL, no 60-min cap)
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 "$PINGGY_TOKEN+a.pinggy.io"
+```
+
+## Procedure — Start a Tunnel and Get the URL
+
+The model SHOULD use the `terminal` tool. The tunnel must stay alive for the duration of the share, so run it as a background process and parse the public URL from stdout.
+
+### 1. Confirm a local origin is up
+
+```bash
+curl -sI http://127.0.0.1:8000/ | head -1
+# expect HTTP/1.x 200 (or any non-connection-refused response)
+```
+
+If nothing is listening yet, start it first (e.g. `python3 -m http.server 8000 --bind 127.0.0.1`). Pinggy will happily return a URL pointed at nothing — the user will see 502 until the origin comes up.
+
+### 2. Launch the tunnel as a background process
+
+Use `terminal(background=True)` and capture output to a logfile (Pinggy prints the URLs on stdout, then keeps the connection open):
+
+```bash
+LOG=/tmp/pinggy-8000.log
+nohup ssh -p 443 \
+    -o StrictHostKeyChecking=no \
+    -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -o ServerAliveCountMax=3 \
+    -R0:localhost:8000 free@a.pinggy.io \
+    > "$LOG" 2>&1 &
+echo $! > /tmp/pinggy-8000.pid
+```
+
+`StrictHostKeyChecking=no` + `UserKnownHostsFile=/dev/null` skips the first-run host-key prompt. `ServerAliveInterval=30` keeps the SSH session from getting torn down by an idle NAT.
+
+### 3. Parse the URL out of the log
+
+```bash
+sleep 4
+grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/pinggy-8000.log | head -1
+```
+
+Expected output looks like:
+
+```
+You are not authenticated.
+Your tunnel will expire in 60 minutes.
+http://yqycl-98-162-69-48.a.free.pinggy.link
+https://yqycl-98-162-69-48.a.free.pinggy.link
+```
+
+Hand the `https://...pinggy.link` URL to the user.
+
+### 4. Verify
+
+```bash
+curl -sI https://<the-url>/ | head -3
+# expect 200/302/whatever the local origin actually returns
+```
+
+If you get `502 Bad Gateway`, the SSH session is up but the local origin isn't listening — fix step 1 first.
+
+### 5. Teardown
+
+```bash
+kill "$(cat /tmp/pinggy-8000.pid)"
+# or, if the pid file got lost:
+pkill -f 'ssh -p 443 .* free@a\.pinggy\.io'
+```
+
+If you have a session_id from `terminal(background=True)`, prefer `process(action='kill', session_id=...)`.
+
+## Access Control via Username Keywords
+
+Pinggy stacks control flags into the SSH username separated by `+`. Always quote the whole `user@host` argument when it contains a `+`:
+
+| Keyword | Effect |
+|---------|--------|
+| `b:user:pass` | HTTP Basic auth gate |
+| `k:token` | Bearer-token header gate (`Authorization: Bearer <token>`) |
+| `w:CIDR` | IP whitelist (single IP or CIDR, repeatable) |
+| `co` | Add `Access-Control-Allow-Origin: *` (CORS) |
+| `x:https` | Force HTTPS — auto-redirect HTTP to HTTPS |
+| `a:Name:Value` | Add request header |
+| `u:Name:Value` | Update request header |
+| `r:Name` | Remove request header |
+| `qr` | Print a QR code of the URL to stdout (handy for mobile sharing) |
+
+Combine freely: `"b:admin:secret+co+x:https+free@a.pinggy.io"`.
+
+## Web Debugger (optional)
+
+Pinggy can mirror the inbound traffic to `localhost:4300` for inspection. Add a local forward to the SSH command:
+
+```bash
+ssh -p 443 -L4300:localhost:4300 -R0:localhost:8000 free@a.pinggy.io
+```
+
+Then open `http://localhost:4300` in a browser to see live request/response pairs.
+
+## Pitfalls
+
+- **60-minute hard cap on the free tier.** The SSH session terminates at the 60-minute mark; the URL goes dead. For longer shares, either use `PINGGY_TOKEN` (Pro) or auto-restart with a shell loop (note that the URL changes on every restart for free-tier).
+- **Free-tier URL is random and changes on restart.** Don't bookmark it, don't paste it into a config file. Re-parse from the log each time.
+- **Concurrent free tunnels are limited to one per source IP.** Starting a second tunnel from the same machine usually kills the first. Pro tier lifts this.
+- **`+` in usernames must be quoted.** Bare `ssh ... b:admin:secret+free@a.pinggy.io` works in bash but breaks under shells that treat `+` specially or when assembled programmatically. Always wrap in double quotes.
+- **Don't tunnel anything sensitive without an access-control flag.** A bare HTTP tunnel is reachable by anyone with the URL. Use `b:`, `k:`, or `w:` for non-public services.
+- **`process(action='log')` may miss SSH banner output.** Pinggy prints the URLs and then the SSH session goes interactive. Always redirect to a logfile and `grep` the file directly — same pattern as `cloudflared-quick-tunnel`.
+- **Host-key prompt on first run.** Default OpenSSH config asks the user to accept Pinggy's host key. Always pass `-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null` for unattended runs.
+- **TCP and TLS tunnels return a `<subdomain>.a.pinggy.online:<port>` pair, not an https URL.** Parse with a different regex (`tcp://` and a port). Don't assume every Pinggy tunnel is HTTP.
+- **Pro mode requires the token as the username, not a flag.** Use `"$PINGGY_TOKEN+a.pinggy.io"` (no `free@`). With a token you can also add `:persistent` for a stable subdomain — see `pinggy.io/docs/`.
+
+## Recipes
+
+Composite patterns combining a local origin with a Pinggy tunnel. Each recipe is self-contained — start the origin, start the tunnel, parse the URL, hand it back to the user.
+
+### Recipe 1 — Receive a webhook callback
+
+Use this when an external service (Stripe, GitHub, Discord, AgentMail, etc.) needs to POST to a publicly reachable URL during a local task.
+
+```bash
+# 1. Tiny capturing server: every request gets appended to /tmp/webhook-hits.log
+cat >/tmp/webhook-server.py <<'PY'
+import http.server, json, datetime, pathlib
+LOG = pathlib.Path("/tmp/webhook-hits.log")
+class H(http.server.BaseHTTPRequestHandler):
+    def _capture(self):
+        n = int(self.headers.get("content-length") or 0)
+        body = self.rfile.read(n).decode("utf-8", "replace") if n else ""
+        rec = {"t": datetime.datetime.utcnow().isoformat(), "path": self.path,
+               "method": self.command, "headers": dict(self.headers), "body": body}
+        with LOG.open("a") as f: f.write(json.dumps(rec) + "\n")
+        self.send_response(200); self.send_header("content-type","application/json")
+        self.end_headers(); self.wfile.write(b'{"ok":true}\n')
+    def do_GET(self): self._capture()
+    def do_POST(self): self._capture()
+    def log_message(self,*a,**k): pass
+http.server.HTTPServer(("127.0.0.1", 18080), H).serve_forever()
+PY
+nohup python3 /tmp/webhook-server.py >/tmp/webhook-server.log 2>&1 &
+echo $! >/tmp/webhook-server.pid
+
+# 2. Tunnel — bearer-token-gate so randos can't pollute the capture log
+nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:18080 "k:$(openssl rand -hex 12)+free@a.pinggy.io" \
+    >/tmp/webhook-pinggy.log 2>&1 &
+echo $! >/tmp/webhook-pinggy.pid
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/webhook-pinggy.log | head -1)
+echo "Webhook URL: $URL"
+
+# 3. While the agent works, watch hits land
+tail -f /tmp/webhook-hits.log
+```
+
+Hand `$URL` to the service that needs to call you. Teardown: `kill $(cat /tmp/webhook-server.pid) $(cat /tmp/webhook-pinggy.pid)`.
+
+### Recipe 2 — Expose an MCP server over HTTP/SSE
+
+Use when a remote MCP client (Claude Desktop on another machine, a teammate's editor, etc.) needs to reach an MCP server running on the local box. Only works for MCP servers that speak HTTP transport — stdio-mode servers can't be tunneled.
+
+```bash
+# 1. Start the MCP server in HTTP mode (example: a FastMCP server on port 8765)
+nohup python3 my_mcp_server.py --transport http --port 8765 \
+    >/tmp/mcp-server.log 2>&1 &
+echo $! >/tmp/mcp-server.pid
+
+# 2. Tunnel with a bearer token — MCP traffic should not be open to the internet
+TOKEN=$(openssl rand -hex 16)
+nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:8765 "k:$TOKEN+free@a.pinggy.io" \
+    >/tmp/mcp-pinggy.log 2>&1 &
+echo $! >/tmp/mcp-pinggy.pid
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/mcp-pinggy.log | head -1)
+echo "MCP URL: $URL"
+echo "Bearer token: $TOKEN"
+```
+
+The remote client connects to `$URL` with `Authorization: Bearer $TOKEN`. Hermes' own native MCP client config: `{"transport": "http", "url": "<URL>", "headers": {"Authorization": "Bearer <TOKEN>"}}`.
+
+### Recipe 3 — Expose a local LLM endpoint (Ollama / vLLM / llama.cpp)
+
+Share a local model with a remote caller (another agent, a phone, a teammate). Ollama listens on `:11434`, vLLM and llama.cpp typically on `:8000`.
+
+```bash
+# Pre-req: the model server is already running on 127.0.0.1:11434 (Ollama default)
+TOKEN=$(openssl rand -hex 16)
+nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:11434 "k:$TOKEN+co+free@a.pinggy.io" \
+    >/tmp/llm-pinggy.log 2>&1 &
+echo $! >/tmp/llm-pinggy.pid
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/llm-pinggy.log | head -1)
+echo "Endpoint: $URL"
+echo "Token:    $TOKEN"
+
+# Verify
+curl -s "$URL/api/tags" -H "Authorization: Bearer $TOKEN" | head
+```
+
+`co` enables CORS so a browser caller can hit the endpoint. Drop `co` for backend-only callers. For an OpenAI-compatible vLLM/llama.cpp endpoint, callers use base URL `$URL/v1` with `Authorization: Bearer $TOKEN` — but note Pinggy strips/replaces nothing in the body, so the model server itself sees Pinggy's token; the local server should be configured to ignore auth (it's already on `127.0.0.1`) and let Pinggy do the gating.
+
+### Recipe 4 — Share a dev server with a one-shot password
+
+The fastest "let a teammate poke at my running app" pattern. Random password, prints once, dies when you Ctrl-C.
+
+```bash
+PASS=$(openssl rand -base64 12 | tr -d '+/=' | head -c 12)
+echo "Dev server password: $PASS"
+ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:3000 "b:dev:$PASS+co+x:https+free@a.pinggy.io"
+# URL prints to the terminal. Share URL + password. Ctrl-C to tear down.
+```
+
+`b:dev:$PASS` gates the URL with HTTP Basic auth. `x:https` forces TLS. `co` adds CORS for SPA frontends.
+
+## Verification
+
+```bash
+# End-to-end: spin up a trivial origin, tunnel it, hit it, tear down
+python3 -m http.server 18000 --bind 127.0.0.1 >/tmp/origin.log 2>&1 &
+ORIGIN_PID=$!
+
+nohup ssh -p 443 \
+    -o StrictHostKeyChecking=no \
+    -o UserKnownHostsFile=/dev/null \
+    -R0:localhost:18000 free@a.pinggy.io >/tmp/pinggy-verify.log 2>&1 &
+SSH_PID=$!
+
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/pinggy-verify.log | head -1)
+echo "URL: $URL"
+curl -sI "$URL/" | head -1
+
+kill "$SSH_PID" "$ORIGIN_PID"
+```
+
+Expected: a `pinggy.link` URL and `HTTP/2 200` on the curl head.