portless
Named .localhost URLs for dev servers, eliminating port conflicts and hardcoded port numbers.
- Assigns random free ports (4000–4999) automatically and routes named subdomains (e.g.
myapp.localhost:1355) to the correct app via a reverse proxy on port 1355 - Auto-detects git worktrees and prepends branch names as subdomain prefixes so each worktree gets a unique URL without configuration changes
- Supports HTTP/2 with HTTPS via auto-generated local CA certificates; includes CLI commands for proxy management, static route registration, and
/etc/hostssyncing for Safari compatibility - Auto-injects
--portand--hostflags for frameworks that ignore thePORTenvironment variable (Vite, Astro, React Router, Angular, Expo, React Native)
Portless
Replace port numbers with stable, named .localhost URLs. For humans and agents.
Why portless
- Port conflicts:
EADDRINUSEwhen two projects default to the same port - Memorizing ports: which app is on 3001 vs 8080?
- Refreshing shows the wrong app: stop one server, start another on the same port, stale tab shows wrong content
- Monorepo multiplier: every problem scales with each service in the repo
- Agents test the wrong port: AI agents guess or hardcode the wrong port
- Cookie/storage clashes: cookies on
localhostbleed across apps; localStorage lost when ports shift - Hardcoded ports in config: CORS allowlists, OAuth redirects,
.envfiles break when ports change - Sharing URLs with teammates: "what port is that on?" becomes a Slack question
- Browser history is useless:
localhost:3000history is a mix of unrelated projects
Installation
Install globally (recommended) or as a project dev dependency. Do NOT use npx or pnpm dlx for one-off execution.
More from vercel-labs/portless
oauth
Configure OAuth providers (Google, Apple, Microsoft, Facebook, GitHub, etc.) to work with portless local dev URLs. Use when setting up OAuth redirect URIs, fixing "redirect_uri_mismatch" or "invalid redirect" errors, configuring sign-in providers for local development, or when a provider rejects .localhost subdomains. Triggers include "OAuth not working with portless", "redirect URI mismatch", "Google/Apple/Microsoft sign-in fails locally", "configure OAuth for local dev", or any task involving OAuth callback URLs with portless domains.
1.4Kskill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
125