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.
\nUpstream: 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, troubleshootingreferences/upstream-oauth.md — OAuth provider compatibility (Google, Apple, Microsoft, Facebook, GitHub), TLD selection for OAuth, callback URI configurationThis 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.
\n| Layer | \nPortless owns | \nPortless does NOT own | \n
|---|---|---|
| Routing | \nhostname → port mapping, HTTPS termination, HTTP/2, CA trust | \nprocess supervision (use Process Compose or PM2) | \n
| Naming | \n<name>.<tld> shape — one TLD per proxy | \nper-service distinct TLDs (not supported) | \n
| Process spawning | \nwhen invoked as portless myapp <cmd> | \ncrash recovery, restart policy, health checks | \n
Key shape constraint: portless always renders <alias-name>.<tld>. You can't mix two TLDs in one proxy because TLD is per-instance — a dotted alias like portless alias api.<app> 8108 gets the TLD appended → api.<app>.<tld>.
# Pin a specific version (zero runtime deps, low supply-chain surface)\nnpm install -g portless@0.13.0\n\n# Verify\nportless --version\nRecord the pinned version in your repo. Upgrades are explicit PRs.
\n# example values — substitute your own (TLD, app name, ports)\n# Proxy lifecycle\nportless proxy start --tld lab --port 443 # HTTPS proxy on 443, *.lab routes\nportless proxy start --tld test --port 1355 # Non-privileged port for testing\nportless proxy stop\nportless trust # Add CA to system trust store\n\n# Aliases (for services portless didn't spawn — PM2, Process Compose, Docker, etc.)\nportless alias axiom 8108 # https://axiom.lab → :8108\nportless alias axiom 8108 --force # Overwrite existing\nportless alias --remove axiom # Note: appends TLD! be careful\n\n# Spawn-mode (portless manages the process)\nportless myapp next dev # https://myapp.lab, auto port 4000-4999\nportless run pnpm dev # Auto-infer name from package.json\n\n# Discovery (agent-friendly)\nportless list # Active routes\nportless get axiom # Returns: https://axiom.lab\n\n# Boot persistence\nportless service install # OS-native startup task\nportless service status\nportless service uninstall\nThe common pattern: a process supervisor (Process Compose, PM2, Docker) runs your dev servers on fixed ports. Portless just routes named URLs to those ports.
\n# Started by Process Compose, listening on <your-port>\n# Now make it reachable at https://<your-app>.<your-tld>\nportless alias <your-app> <your-port>\nDecoupling means:
\npm2 restart <your-app>, process-compose process restart <your-app>) → portless keeps routing transparentlySource of truth pattern: keep alias registration in your supervisor config. Example scripts/install.ps1:
$services = (yq '.processes | keys | .[]' process-compose.yaml)\nforeach ($svc in $services) {\n $port = (yq \".processes.$svc.readiness_probe.http_get.port\" process-compose.yaml)\n if ($port -and $port -ne \"null\") {\n portless alias $svc $port --force\n }\n}\n| TLD | \nWhen to use | \nCaveats | \n
|---|---|---|
.localhost (default) | \nQuickest start | \nAuto-resolves to 127.0.0.1 on most systems | \n
.lab | \nPersonal/distinctive | \nNot IANA-reserved (no DNS collision in practice for local) | \n
.test | \nOAuth-friendly | \nIANA-reserved; safe | \n
.dev | \nOAuth (Google, Apple) | \nGoogle-owned, forces HTTPS — portless handles this fine | \n
.local | \nAvoid | \nmDNS/Bonjour conflict | \n
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.
# Stop proxy\nportless proxy stop\n\n# Wipe all aliases (routes.json)\nrm ~/.portless/routes.json # Linux/macOS\nRemove-Item \"$env:USERPROFILE\\.portless\\routes.json\" # PowerShell\n\n# Start fresh with desired TLD\nportless proxy start --tld <tld> --port 443\n\n# Re-register aliases from your supervisor config\nThis is the right pattern when you change TLD — portless alias --remove appends the active TLD which makes it fight you.
openssl required on PATHPortless uses OpenSSL to generate the local CA. Git for Windows ships it:
\n# Persistent: add to user PATH\n$gitBin = \"C:\\Program Files\\Git\\usr\\bin\"\n$current = [Environment]::GetEnvironmentVariable(\"PATH\", \"User\")\nif ($current -notlike \"*$gitBin*\") {\n [Environment]::SetEnvironmentVariable(\"PATH\", \"$gitBin;$current\", \"User\")\n}\nWithout it: Error: openssl failed: spawnSync openssl ENOENT
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:
\nGet-ScheduledTask | Where-Object {\n $_.TaskName -like \"*ortless*\" -or $_.TaskName -like \"*ompose*\"\n}\ncurl on Windows uses its own bundled CA store, not the system one. So curl https://<your-app>.<your-tld>/ 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://<your-app>.<your-tld>/ # quick test\ncurl --cacert ~/.portless/ca.pem https://<your-app>.<your-tld>/ # proper\n| Error | \nCause | \nFix | \n
|---|---|---|
openssl failed: spawnSync openssl ENOENT | \nOpenSSL not on PATH | \nAdd Git's usr/bin to PATH | \n
Error: No alias found for \"foo.lab\" (you asked for foo) | \n--remove appends TLD; sometimes adds an extra | \nWipe routes.json and re-register | \n
| Browser shows cert warning | \nCA not in system trust store | \nRe-run portless trust (may need admin) | \n
https://name.lab shows \"No app registered\" | \nAlias not set or proxy stopped | \nportless list to confirm; re-register if needed | \n
Safari can't resolve *.lab | \nSafari uses system DNS, not Node's resolver | \nportless hosts sync to write /etc/hosts | \n
Port 443 conflict on portless proxy start | \nAnother service bound (Caddy, IIS) | \nStop the other service, or use --port 1355 for testing | \n
A PM2+Caddy to Process Compose+portless migration is worth keeping in its own small repo (e.g. ~/infra/local-stack/), with these key files:
process-compose.yaml — supervisor config with health-checked servicesscripts/cutover.ps1 — stops PM2/Caddy, starts portless+PC, registers aliasesdocs/MIGRATION-LOG.md — every issue hit during cutover and how it was solveddocs/SUPPLY-CHAIN.md — pinning + verification proceduresBAD: portless alias name 8000; portless alias name 8001 # second silently fails without --force\nGOOD: portless alias name 8001 --force\n\nBAD: use portless as production reverse proxy\nGOOD: keep portless as dev-only; production = nginx/Caddy/cloud LB\n\nBAD: rely on portless for crash recovery (it has none for spawned processes)\nGOOD: pair portless with Process Compose / PM2 / supervisord for supervision\n\nBAD: change TLD by stopping/starting with different --tld and hoping aliases update\nGOOD: stop proxy, wipe routes.json, start with new TLD, re-register from supervisor config\nreferences/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/GitHubtld-selection.md — decision tree for picking the right TLD; trade-offs of .test/.dev/.localhost/custom-ownedwindows-specifics.md — openssl PATH, certutil quirks, curl-vs-browser cert handling, PS 5.1 gotchasintegration-patterns.md — combos with Process Compose / Docker / PM2 / Tailscale / git worktreesscripts/install-portless.ps1 — verified install: inspect tarball, scan for IOCs from recent attacks, install only if cleanreset-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.yamlassets/portless.json.simple.json — single-app config templateportless.json.monorepo.json — workspace monorepo with name overridesportless.json.with-custom-tld.json — documents TLD choice in repopackage.json-portless-key.json — alternative: portless config inside package.jsonprocess-compose-ops — the supervisor we pair with portlessmcp-ops — agent-friendly tooling; portless get <name> provides URL discovery for agentscli-ops — general CLI tool patterns