portless-ops

What this skill does

# 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](https://github.com/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`](references/upstream-portless.md)** — full CLI reference, integration patterns (zero-config, monorepo, turborepo, worktrees, Tailscale), HTTPS/LAN setup, troubleshooting
- **[`references/upstream-oauth.md`](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

```bash
# Pin a specific version (zero runtime deps, low supply-chain surface)
npm install -g [email protected]

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

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`](references/upstream-oauth.md) for full per-provider setup.

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