Set up and use portless for named local dev server URLs (e.g. http://myapp.localhost instead of http://localhost:3000). Use when integrating portless into a project, configuring dev server names, setting up the local proxy, working with .localhost domains, or troubleshooting port/proxy issues.
Replace port numbers with stable, named .localhost URLs. For humans and agents.
EADDRINUSE when two projects default to the same portlocalhost bleed across apps; localStorage lost when ports shift.env files break when ports changelocalhost:3000 history is a mix of unrelated projectsportless is a global CLI tool. Do NOT add it as a project dependency (no npm install portless or pnpm add portless in a project). Do NOT use npx.
Install globally:
npm install -g portless
# Install globally
npm install -g portless
# Start the proxy (once, no sudo needed)
portless proxy start
# Run your app (auto-starts the proxy if needed)
portless myapp next dev
# -> http://myapp.localhost:1355
The proxy auto-starts when you run an app. You can also start it explicitly with portless proxy start.
{
"scripts": {
"dev": "portless myapp next dev"
}
}
The proxy auto-starts when you run an app. Or start it explicitly: portless proxy start.
portless myapp next dev # http://myapp.localhost:1355
portless api.myapp pnpm start # http://api.myapp.localhost:1355
portless docs.myapp next dev # http://docs.myapp.localhost:1355
Set PORTLESS=0 or PORTLESS=skip to run the command directly without the proxy:
PORTLESS=0 pnpm dev # Bypasses proxy, uses default port
portless proxy start starts an HTTP reverse proxy on port 1355 as a background daemon (configurable with -p / --port or the PORTLESS_PORT env var). The proxy also auto-starts when you run an app.portless <name> <cmd> assigns a random free port (4000-4999) via the PORT env var and registers the app with the proxyhttp://<name>.localhost:1355 on the proxy port; the proxy forwards to the app's assigned port.localhost domains resolve to 127.0.0.1 natively on macOS and Linux -- no /etc/hosts editing needed.
Most frameworks (Next.js, Express, Nuxt, etc.) respect the PORT env var automatically. For frameworks that ignore PORT (Vite, Astro, React Router, Angular), portless auto-injects the correct --port and --host CLI flags.
| Command | Description |
|---|---|
portless <name> <cmd> [args...] | Run app at http://<name>.localhost:1355 (auto-starts proxy) |
portless list | Show active routes |
portless trust | Add local CA to system trust store (for HTTPS) |
portless proxy start | Start the proxy as a daemon (port 1355, no sudo) |
portless proxy start --https | Start with HTTP/2 + TLS (auto-generates certs) |
portless proxy start -p <number> | Start the proxy on a custom port |
portless proxy start --foreground | Start the proxy in foreground (for debugging) |
portless proxy stop | Stop the proxy |
portless <name> --force <cmd> | Override an existing route registered by another process |
portless --help / -h | Show help |
portless --version / -v | Show version |
The proxy auto-starts when you run an app. If it doesn't start, start it manually: portless proxy start
Use a different port: portless proxy start -p 8080
Portless auto-injects flags for Vite, Astro, React Router, Angular. For others, pass --port $PORT manually.
Set changeOrigin: true in proxy config when dev server proxies to another portless app.