mindforge-cc 11.5.1 → 11.7.0

package/.agent/skills/parallel-cli/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: parallel-cli
+description: Optional vendor skill for Parallel CLI — agent-native web search, extraction, deep research, enrichment, FindAll, and monitoring. Prefer JSON output and non-interactive flows.
+version: 1.1.0
+---
+
+# Parallel CLI
+
+Use `parallel-cli` when the user explicitly wants Parallel, or when a terminal-native workflow would benefit from Parallel's vendor-specific stack for web search, extraction, deep research, enrichment, entity discovery, or monitoring.
+
+This is an optional third-party workflow, not a a core capability.
+
+Important expectations:
+- Parallel is a paid service with a free tier, not a fully free local tool.
+- It overlaps with native `web_search` / `web_extract`, so do not prefer it by default for ordinary lookups.
+- Prefer this skill when the user mentions Parallel specifically or needs capabilities like Parallel's enrichment, FindAll, or monitor workflows.
+
+`parallel-cli` is designed for agents:
+- JSON output via `--json`
+- Non-interactive command execution
+- Async long-running jobs with `--no-wait`, `status`, and `poll`
+- Context chaining with `--previous-interaction-id`
+- Search, extract, research, enrichment, entity discovery, and monitoring in one CLI
+
+## When to use it
+
+Prefer this skill when:
+- The user explicitly mentions Parallel or `parallel-cli`
+- The task needs richer workflows than a simple one-shot search/extract pass
+- You need async deep research jobs that can be launched and polled later
+- You need structured enrichment, FindAll entity discovery, or monitoring
+
+Prefer native `web_search` / `web_extract` for quick one-off lookups when Parallel is not specifically requested.
+
+## Installation
+
+Try the least invasive install path available for the environment.
+
+### Homebrew
+
+```bash
+brew install parallel-web/tap/parallel-cli
+```
+
+### npm
+
+```bash
+npm install -g parallel-web-cli
+```
+
+### Python package
+
+```bash
+pip install "parallel-web-tools[cli]"
+```
+
+### Standalone installer
+
+```bash
+curl -fsSL https://parallel.ai/install.sh | bash
+```
+
+If you want an isolated Python install, `pipx` can also work:
+
+```bash
+pipx install "parallel-web-tools[cli]"
+pipx ensurepath
+```
+
+## Authentication
+
+Interactive login:
+
+```bash
+parallel-cli login
+```
+
+Headless / SSH / CI:
+
+```bash
+parallel-cli login --device
+```
+
+API key environment variable:
+
+```bash
+export PARALLEL_API_KEY="***"
+```
+
+Verify current auth status:
+
+```bash
+parallel-cli auth
+```
+
+If auth requires browser interaction, run with `pty=true`.
+
+## Core rule set
+
+1. Always prefer `--json` when you need machine-readable output.
+2. Prefer explicit arguments and non-interactive flows.
+3. For long-running jobs, use `--no-wait` and then `status` / `poll`.
+4. Cite only URLs returned by the CLI output.
+5. Save large JSON outputs to a temp file when follow-up questions are likely.
+6. Use background processes only for genuinely long-running workflows; otherwise run in foreground.
+7. Prefer native tools unless the user wants Parallel specifically or needs Parallel-only workflows.
+
+## Quick reference
+
+```text
+parallel-cli
+├── auth
+├── login
+├── logout
+├── search
+├── extract / fetch
+├── research run|status|poll|processors
+├── enrich run|status|poll|plan|suggest|deploy
+├── findall run|ingest|status|poll|result|enrich|extend|schema|cancel
+└── monitor create|list|get|update|delete|events|event-group|simulate
+```
+
+## Common flags and patterns
+
+Commonly useful flags:
+- `--json` for structured output
+- `--no-wait` for async jobs
+- `--previous-interaction-id <id>` for follow-up tasks that reuse earlier context
+- `--max-results <n>` for search result count
+- `--mode one-shot|agentic` for search behavior
+- `--include-domains domain1.com,domain2.com`
+- `--exclude-domains domain1.com,domain2.com`
+- `--after-date YYYY-MM-DD`
+
+Read from stdin when convenient:
+
+```bash
+echo "What is the latest funding for Anthropic?" | parallel-cli search - --json
+echo "Research question" | parallel-cli research run - --json
+```
+
+## Search
+
+Use for current web lookups with structured results.
+
+```bash
+parallel-cli search "What is Anthropic's latest AI model?" --json
+parallel-cli search "SEC filings for Apple" --include-domains sec.gov --json
+parallel-cli search "bitcoin price" --after-date 2026-01-01 --max-results 10 --json
+parallel-cli search "latest browser benchmarks" --mode one-shot --json
+parallel-cli search "AI coding agent enterprise reviews" --mode agentic --json
+```
+
+Useful constraints:
+- `--include-domains` to narrow trusted sources
+- `--exclude-domains` to strip noisy domains
+- `--after-date` for recency filtering
+- `--max-results` when you need broader coverage
+
+If you expect follow-up questions, save output:
+
+```bash
+parallel-cli search "latest React 19 changes" --json -o /tmp/react-19-search.json
+```
+
+When summarizing results:
+- lead with the answer
+- include dates, names, and concrete facts
+- cite only returned sources
+- avoid inventing URLs or source titles
+
+## Extraction
+
+Use to pull clean content or markdown from a URL.
+
+```bash
+parallel-cli extract https://example.com --json
+parallel-cli extract https://company.com --objective "Find pricing info" --json
+parallel-cli extract https://example.com --full-content --json
+parallel-cli fetch https://example.com --json
+```
+
+Use `--objective` when the page is broad and you only need one slice of information.
+
+## Deep research
+
+Use for deeper multi-step research tasks that may take time.
+
+Common processor tiers:
+- `lite` / `base` for faster, cheaper passes
+- `core` / `pro` for more thorough synthesis
+- `ultra` for the heaviest research jobs
+
+### Synchronous
+
+```bash
+parallel-cli research run \
+  "Compare the leading AI coding agents by pricing, model support, and enterprise controls" \
+  --processor core \
+  --json
+```
+
+### Async launch + poll
+
+```bash
+parallel-cli research run \
+  "Compare the leading AI coding agents by pricing, model support, and enterprise controls" \
+  --processor ultra \
+  --no-wait \
+  --json
+
+parallel-cli research status trun_xxx --json
+parallel-cli research poll trun_xxx --json
+parallel-cli research processors --json
+```
+
+### Context chaining / follow-up
+
+```bash
+parallel-cli research run "What are the top AI coding agents?" --json
+parallel-cli research run \
+  "What enterprise controls does the top-ranked one offer?" \
+  --previous-interaction-id trun_xxx \
+  --json
+```
+
+Recommended workflow:
+1. launch with `--no-wait --json`
+2. capture the returned run/task ID
+3. if the user wants to continue other work, keep moving
+4. later call `status` or `poll`
+5. summarize the final report with citations from the returned sources
+
+## Enrichment
+
+Use when the user has CSV/JSON/tabular inputs and wants additional columns inferred from web research.
+
+### Suggest columns
+
+```bash
+parallel-cli enrich suggest "Find the CEO and annual revenue" --json
+```
+
+### Plan a config
+
+```bash
+parallel-cli enrich plan -o config.yaml
+```
+
+### Inline data
+
+```bash
+parallel-cli enrich run \
+  --data '[{"company": "Anthropic"}, {"company": "Mistral"}]' \
+  --intent "Find headquarters and employee count" \
+  --json
+```
+
+### Non-interactive file run
+
+```bash
+parallel-cli enrich run \
+  --source-type csv \
+  --source companies.csv \
+  --target enriched.csv \
+  --source-columns '[{"name": "company", "description": "Company name"}]' \
+  --intent "Find the CEO and annual revenue"
+```
+
+### YAML config run
+
+```bash
+parallel-cli enrich run config.yaml
+```
+
+### Status / polling
+
+```bash
+parallel-cli enrich status <task_group_id> --json
+parallel-cli enrich poll <task_group_id> --json
+```
+
+Use explicit JSON arrays for column definitions when operating non-interactively.
+Validate the output file before reporting success.
+
+## FindAll
+
+Use for web-scale entity discovery when the user wants a discovered dataset rather than a short answer.
+
+```bash
+parallel-cli findall run "Find AI coding agent startups with enterprise offerings" --json
+parallel-cli findall run "AI startups in healthcare" -n 25 --json
+parallel-cli findall status <run_id> --json
+parallel-cli findall poll <run_id> --json
+parallel-cli findall result <run_id> --json
+parallel-cli findall schema <run_id> --json
+```
+
+This is a better fit than ordinary search when the user wants a discovered set of entities that can be reviewed, filtered, or enriched later.
+
+## Monitor
+
+Use for ongoing change detection over time.
+
+```bash
+parallel-cli monitor list --json
+parallel-cli monitor get <monitor_id> --json
+parallel-cli monitor events <monitor_id> --json
+parallel-cli monitor delete <monitor_id> --json
+```
+
+Creation is usually the sensitive part because cadence and delivery matter:
+
+```bash
+parallel-cli monitor create --help
+```
+
+Use this when the user wants recurring tracking of a page or source rather than a one-time fetch.
+
+## Recommended usage patterns
+
+### Fast answer with citations
+1. Run `parallel-cli search ... --json`
+2. Parse titles, URLs, dates, excerpts
+3. Summarize with inline citations from the returned URLs only
+
+### URL investigation
+1. Run `parallel-cli extract URL --json`
+2. If needed, rerun with `--objective` or `--full-content`
+3. Quote or summarize the extracted markdown
+
+### Long research workflow
+1. Run `parallel-cli research run ... --no-wait --json`
+2. Store the returned ID
+3. Continue other work or periodically poll
+4. Summarize the final report with citations
+
+### Structured enrichment workflow
+1. Inspect the input file and columns
+2. Use `enrich suggest` or provide explicit enriched columns
+3. Run `enrich run`
+4. Poll for completion if needed
+5. Validate the output file before reporting success
+
+## Error handling and exit codes
+
+The CLI documents these exit codes:
+- `0` success
+- `2` bad input
+- `3` auth error
+- `4` API error
+- `5` timeout
+
+If you hit auth errors:
+1. check `parallel-cli auth`
+2. confirm `PARALLEL_API_KEY` or run `parallel-cli login` / `parallel-cli login --device`
+3. verify `parallel-cli` is on `PATH`
+
+## Maintenance
+
+Check current auth / install state:
+
+```bash
+parallel-cli auth
+parallel-cli --help
+```
+
+Update commands:
+
+```bash
+parallel-cli update
+pip install --upgrade parallel-web-tools
+parallel-cli config auto-update-check off
+```
+
+## Pitfalls
+
+- Do not omit `--json` unless the user explicitly wants human-formatted output.
+- Do not cite sources not present in the CLI output.
+- `login` may require PTY/browser interaction.
+- Prefer foreground execution for short tasks; do not overuse background processes.
+- For large result sets, save JSON to `/tmp/*.json` instead of stuffing everything into context.
+- Do not silently choose Parallel when native tools are already sufficient.
+- Remember this is a vendor workflow that usually requires account auth and paid usage beyond the free tier.

package/.agent/skills/pinggy-tunnel/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: pinggy-tunnel
+description: Zero-install localhost tunnels over SSH via Pinggy.
+version: 0.1.0
+---
+
+# 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`. the agent' 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.