git:20260512.54dd06e to git:20260512.f9a7ce4

---

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 <name>, 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.

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

```bash

# 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

```bash

# 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.

```bash

# 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`:

```powershell

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

## Reset (clean slate)

```bash

# 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:

```powershell

# 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:

```powershell

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`:

```bash

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

```

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