Home Esplora Aiuto
Accedi
logic855
/
claude-mods
mirror da https://github.com/0xDarkMatter/claude-mods.git
1
0
Forka 0
File Problemi 0 Wiki
Ramo (Branch): main
Rami (Branch) Tag
claude-mods
/
skills
/
portless-ops
/
SKILL.md

SKILL.md 11 KB
Permalink Cronologia Originale

name: portless-ops description: "Portless local-dev HTTPS proxy operations and integration. Use for: portless setup, named .localhost or custom-TLD URLs (axiom.lab, myapp.test), portless alias for externally-managed services, replacing Caddy/nginx for local dev, HTTP/2 dev servers, local CA generation and trust, portless service install (boot persistence on Windows/macOS/Linux), portless monorepo orchestration, Tailscale/Funnel dev sharing, git-worktree subdomain routing, portless.json configuration, agent-friendly URL discovery via portless get , MCP-integration patterns, OAuth-with-portless TLD selection (.dev/.test for Google/Apple compliance), Vite/Next.js/Astro framework port injection, Windows openssl PATH gotcha, curl-vs-browser cert handling, custom TLD pitfalls (.local/.dev/.localhost), troubleshooting EADDRINUSE, /etc/hosts auto-sync, portless trust system store integration." license: MIT allowed-tools: "Read Write Bash Edit" metadata: author: claude-mods related-skills: process-compose-ops, mcp-ops, cli-ops

upstream: https://github.com/vercel-labs/portless

Portless Operations

Portless (Vercel Labs) is a local-dev HTTPS proxy that replaces port numbers with named URLs. Replacement for Caddy/nginx in the local-dev role; not for production.

Upstream: vercel-labs/portless (Apache-2.0). The portless repo ships canonical skills in its source tree (not in the npm package). Verbatim copies kept in references/:

  • references/upstream-portless.md — full CLI reference, integration patterns (zero-config, monorepo, turborepo, worktrees, Tailscale), HTTPS/LAN setup, troubleshooting
  • references/upstream-oauth.md — OAuth provider compatibility (Google, Apple, Microsoft, Facebook, GitHub), TLD selection for OAuth, callback URI configuration

This SKILL.md adds operational patterns we've validated in production (Windows specifics, the static-alias-with-supervisor pattern, TLD-reset procedure, supply-chain hygiene). For canonical CLI usage, prefer the upstream reference files.

Mental Model

Layer Portless owns Portless does NOT own
Routing hostname → port mapping, HTTPS termination, HTTP/2, CA trust process supervision (use Process Compose or PM2)
Naming <name>.<tld> shape — one TLD per proxy per-service distinct TLDs (not supported)
Process spawning when invoked as portless myapp <cmd> crash recovery, restart policy, health checks

Key shape constraint: portless always renders <alias-name>.<tld>. You can't have 0x.axiom and axiom.lab in the same proxy because TLD is per-instance. Aliases like portless alias 0x.axiom 8108 get the TLD appended → 0x.axiom.lab.

Install

# Pin a specific version (zero runtime deps, low supply-chain surface)
npm install -g portless@0.13.0

# Verify
portless --version

Record the pinned version in your repo. Upgrades are explicit PRs.

CLI Quick Reference

# Proxy lifecycle
portless proxy start --tld lab --port 443   # HTTPS proxy on 443, *.lab routes
portless proxy start --tld test --port 1355 # Non-privileged port for testing
portless proxy stop
portless trust                              # Add CA to system trust store

# Aliases (for services portless didn't spawn — PM2, Process Compose, Docker, etc.)
portless alias axiom 8108                   # https://axiom.lab → :8108
portless alias axiom 8108 --force           # Overwrite existing
portless alias --remove axiom               # Note: appends TLD! be careful

# Spawn-mode (portless manages the process)
portless myapp next dev                     # https://myapp.lab, auto port 4000-4999
portless run pnpm dev                       # Auto-infer name from package.json

# Discovery (agent-friendly)
portless list                               # Active routes
portless get axiom                          # Returns: https://axiom.lab

# Boot persistence
portless service install                    # OS-native startup task
portless service status
portless service uninstall

The Static-Alias Pattern (portless + external process supervisor)

The common pattern: a process supervisor (Process Compose, PM2, Docker) runs your dev servers on fixed ports. Portless just routes named URLs to those ports.

# Started by Process Compose, listening on 8108
# Now make it reachable at https://axiom.lab
portless alias axiom 8108

Decoupling means:

  • Restart the dev server (pm2 restart axiom, process-compose process restart axiom) → portless keeps routing transparently
  • Swap one supervisor for another → portless layer is untouched

Source of truth pattern: keep alias registration in your supervisor config. Example scripts/install.ps1:

$services = (yq '.processes | keys | .[]' process-compose.yaml)
foreach ($svc in $services) {
  $port = (yq ".processes.$svc.readiness_probe.http_get.port" process-compose.yaml)
  if ($port -and $port -ne "null") {
    portless alias $svc $port --force
  }
}

TLD Selection

TLD When to use Caveats
.localhost (default) Quickest start Auto-resolves to 127.0.0.1 on most systems
.lab Personal/distinctive Not IANA-reserved (no DNS collision in practice for local)
.test OAuth-friendly IANA-reserved; safe
.dev OAuth (Google, Apple) Google-owned, forces HTTPS — portless handles this fine
.local Avoid mDNS/Bonjour conflict

OAuth providers reject .localhost subdomains (not in Public Suffix List). Switch to --tld test or --tld dev for OAuth dev work. See references/upstream-oauth.md for full per-provider setup.

Reset (clean slate)

# Stop proxy
portless proxy stop

# Wipe all aliases (routes.json)
rm ~/.portless/routes.json    # Linux/macOS
Remove-Item "$env:USERPROFILE\.portless\routes.json"   # PowerShell

# Start fresh with desired TLD
portless proxy start --tld <tld> --port 443

# Re-register aliases from your supervisor config

This is the right pattern when you change TLD — portless alias --remove appends the active TLD which makes it fight you.

Windows-Specific Notes

openssl required on PATH

Portless uses OpenSSL to generate the local CA. Git for Windows ships it:

# Persistent: add to user PATH
$gitBin = "C:\Program Files\Git\usr\bin"
$current = [Environment]::GetEnvironmentVariable("PATH", "User")
if ($current -notlike "*$gitBin*") {
    [Environment]::SetEnvironmentVariable("PATH", "$gitBin;$current", "User")
}

Without it: Error: openssl failed: spawnSync openssl ENOENT

Boot persistence

portless service install registers a Task Scheduler entry. Pair it with your supervisor's own boot task (e.g., for Process Compose, register a separate task via scripts/boot-task-install.ps1).

Verify both registered:

Get-ScheduledTask | Where-Object {
    $_.TaskName -like "*ortless*" -or $_.TaskName -like "*ompose*"
}

curl vs browser cert handling

curl on Windows uses its own bundled CA store, not the system one. So curl https://axiom.lab/ returns code 000 (cert untrusted) even after portless trust. Browsers work fine because they use the system store.

Test from curl with -k (skip verify), or --cacert ~/.portless/ca.pem:

curl -k https://axiom.lab/        # quick test
curl --cacert ~/.portless/ca.pem https://axiom.lab/   # proper

Common Errors

Error Cause Fix
openssl failed: spawnSync openssl ENOENT OpenSSL not on PATH Add Git's usr/bin to PATH
Error: No alias found for "foo.lab" (you asked for foo) --remove appends TLD; sometimes adds an extra Wipe routes.json and re-register
Browser shows cert warning CA not in system trust store Re-run portless trust (may need admin)
https://name.lab shows "No app registered" Alias not set or proxy stopped portless list to confirm; re-register if needed
Safari can't resolve *.lab Safari uses system DNS, not Node's resolver portless hosts sync to write /etc/hosts
Port 443 conflict on portless proxy start Another service bound (Caddy, IIS) Stop the other service, or use --port 1355 for testing

Worked Example: Replacing Caddy with portless

See ~/X/00_Orchestration/compose-portless/ for a worked migration from PM2+Caddy to Process Compose+portless. Key files:

  • process-compose.yaml — supervisor config with health-checked services
  • scripts/cutover.ps1 — stops PM2/Caddy, starts portless+PC, registers aliases
  • docs/MIGRATION-LOG.md — every issue hit during cutover and how it was solved
  • docs/SUPPLY-CHAIN.md — pinning + verification procedures

Anti-Patterns

BAD:  portless alias name 8000; portless alias name 8001   # second silently fails without --force
GOOD: portless alias name 8001 --force

BAD:  use portless as production reverse proxy
GOOD: keep portless as dev-only; production = nginx/Caddy/cloud LB

BAD:  rely on portless for crash recovery (it has none for spawned processes)
GOOD: pair portless with Process Compose / PM2 / supervisord for supervision

BAD:  change TLD by stopping/starting with different --tld and hoping aliases update
GOOD: stop proxy, wipe routes.json, start with new TLD, re-register from supervisor config

Resources in this skill

references/

  • upstream-portless.md — canonical portless SKILL.md verbatim (CLI ref, monorepo, turborepo, worktrees, LAN, Tailscale, HTTPS, troubleshooting)
  • upstream-oauth.md — canonical OAuth setup for Google/Apple/Microsoft/Facebook/GitHub
  • tld-selection.md — decision tree for picking the right TLD; trade-offs of .test/.dev/.localhost/custom-owned
  • windows-specifics.md — openssl PATH, certutil quirks, curl-vs-browser cert handling, PS 5.1 gotchas
  • integration-patterns.md — combos with Process Compose / Docker / PM2 / Tailscale / git worktrees

scripts/

  • install-portless.ps1 — verified install: inspect tarball, scan for IOCs from recent attacks, install only if clean
  • reset-state.ps1 — clean state reset (used when changing TLD; --remove can't clear old-TLD aliases)
  • sync-aliases-from-yaml.ps1 — derive portless aliases from a process-compose.yaml

assets/

  • portless.json.simple.json — single-app config template
  • portless.json.monorepo.json — workspace monorepo with name overrides
  • portless.json.with-custom-tld.json — documents TLD choice in repo
  • package.json-portless-key.json — alternative: portless config inside package.json

Related Skills

  • process-compose-ops — the supervisor we pair with portless
  • mcp-ops — agent-friendly tooling; portless get <name> provides URL discovery for agents
  • cli-ops — general CLI tool patterns