{
  "id": "page:docs-research-portless",
  "_kind": "Page",
  "_file": "wiki/docs/research/portless.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/research/portless.md",
    "sourceKind": "repo-docs",
    "title": "Portless — no port conflicts, worktree-friendly",
    "displayName": "Portless — no port conflicts, worktree-friendly",
    "slug": "docs/research/portless",
    "articlePath": "wiki/docs/research/portless.md",
    "article": "\n# Portless — no port conflicts, worktree-friendly\n\n> **Status:** Assimilation research note (no code change beyond the atlas record).\n> **Date:** 2026-06-23.\n> **Tagline (requester):** \"No port conflicts. Worktree-friendly.\"\n> **Method:** vendor homepage <https://portless.sh> + npm/GitHub corroboration. Behavioral claims are vendor-stated and not independently exercised.\n> **Provenance (verified 2026-06-23):** open source, **Apache-2.0**, by **Vercel Labs** — `github.com/vercel-labs/portless`, npm `portless` (v0.14.0; npm description \"for humans and agents\").\n> **Atlas record:** `tool:portless` — `packages/atlas/graph/domain/tools/portless.yaml` (evidence `evidence:portless-homepage-2026-06`, `evidence:portless-npm-2026-06`).\n\n---\n\n## 0. Bottom line\n\nReplaces local-dev port numbers with stable, named **`.localhost`** HTTPS URLs. Instead of `http://localhost:3000` you get `https://myapp.localhost`, and parallel git worktrees get their own branch-prefixed subdomains automatically — so concurrent checkouts never fight over ports.\n\n## 1. What it does\n\nGives each local app a stable named HTTPS hostname and proxies it to whatever port the app actually bound, eliminating hardcoded-port collisions across projects and worktrees.\n\n## 2. How it works\n\n- Runs an **HTTPS reverse proxy on port 443** by default.\n- Each app registers a route mapping its hostname → an assigned port (randomly picked in **4000–4999**).\n- Requests to the named URL are proxied to the running app.\n- **HTTPS/HTTP-2 by default** with an auto-generated, auto-trusted local CA.\n- **Framework auto-detection** — respects `PORT` and injects the right flags for Vite, Astro, React Router, etc.\n- **Git worktree support** — the branch name is auto-prepended as a subdomain (`fix-ui.myapp.localhost`) with zero config.\n- Auto-syncs `/etc/hosts`; custom TLD (e.g. `.test`) via `--tld`.\n\n## 3. Install & usage\n\n```bash\nnpm install -g portless          # requires Node.js 24+\nportless                          # runs package.json \"dev\" through the proxy\nportless myapp next dev           # proxy a command explicitly\nportless api.myapp pnpm start     # subdomains for multiple services\n```\n\n## 4. Why it's worktree-friendly (relevant to babysitter)\n\nThis repo runs heavily in **git worktrees** (agent isolation, parallel runs). Port collisions between concurrent worktrees are a real friction point for any dev-server / live test. Portless's automatic branch-subdomain routing means N worktrees can each run a dev server without manual port juggling — a clean fit for parallel orchestrated runs. Recorded as catalog awareness; not wired into babysitter tooling.\n\n## 5. Comparison (atlas edges)\n\n`alternative_to`: `tool:ngrok` — ngrok exposes local servers via **public** tunnels; Portless provides stable **local** named HTTPS routes with worktree-aware subdomains.\n\n## 6. Caveats / open questions\n\n- License/OSS/repo **verified** (Apache-2.0, Vercel Labs) via npm + GitHub. Early version (0.14.x).\n- Windows `hosts`/CA behavior, the Node 24+ floor, and any port-443 privilege requirement are unverified against real use.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs",
      "to": "page:docs-research-portless",
      "kind": "contains_page"
    }
  ]
}