Stop Juggling Port Numbers: Portless Gives Your Dev Servers Named URLs

Every developer has been here. You've got three terminals open. One is running your frontend on localhost:3000, the API is on localhost:8080, and the docs site is… wait, was it 3001 or 3002? You switch to a browser tab that says localhost:3000 and it's showing something completely different from what you started on that port an hour ago.

Port number management is a low-grade tax on your productivity that compounds the more services you run. It's one of those pain points so familiar that most developers have just accepted it as part of the job.

Portless, a new tool from Vercel Labs, says no to that.

What Portless Actually Does

Portless replaces numeric port-based local URLs with stable, named .localhost URLs. Instead of localhost:3000, your app runs at http://myapp.localhost:1355.

The concept is simple: a lightweight local proxy runs in the background on port 1355. You start your apps through portless, it assigns them a random ephemeral port internally, and routes requests from your named URL to wherever the app is actually listening. You never see the ephemeral port. You just use the name.

# Before portless
npm run dev   # http://localhost:3000 ... or was it 3001?

# After portless
portless myapp next dev   # http://myapp.localhost:1355. Every time.

You can also run subdomains for microservice setups:

portless api.myapp pnpm start    # http://api.myapp.localhost:1355
portless docs.myapp next dev     # http://docs.myapp.localhost:1355

And if you want it baked into your package.json:

{
  "scripts": {
    "dev": "portless myapp next dev"
  }
}

That's it. One line change. The proxy auto-starts when you run an app — you don't have to manage it separately unless you want to.

The Problems It Actually Solves

Let's be specific about what port-based development breaks in practice.

Port conflicts. EADDRINUSE is one of the most annoying errors in local development. You forgot you left a process running, or two services are both defaulting to 3000. With portless, your app gets an ephemeral port in the 4000–4999 range assigned automatically, so conflicts essentially stop happening.

Cookie and storage bleed. Cookies set on localhost bleed across apps on different ports. localStorage is lost when ports shift. This is subtle but genuinely broken behavior. If you've ever had session state from one app mysteriously show up in another, this is why. Named subdomains give each app its own isolated cookie and storage scope.

The "wrong tab" problem. Stop one server, start another on the same port, and your open browser tab now shows something completely different. With named URLs, http://myapp.localhost:1355 always shows myapp. Period.

Browser history uselessness. Your history for localhost:3000 is a jumbled mess of unrelated projects across months of work. Named URLs make your history actually navigable.

Monorepo chaos. All of these problems scale with every service you add. In a monorepo running five services, port management becomes a real cognitive load.

The AI Agent Angle — and Why It Matters

There's a part of this that caught my attention beyond the developer quality-of-life improvements.

As AI coding agents become more common in development workflows, they need a reliable way to know where services are running. An agent that can reference api.myapp.localhost:1355 instead of guessing whether the API is on port 3001 or 8080 is significantly more likely to get things right on the first try.

This is real. If you use Claude Code, Cursor, or any other coding agent to help you with development tasks, you've probably seen the port-guessing problem firsthand. Agents either hardcode a port they saw earlier in context, or they ask you — interrupting the flow. With portless, the URL is stable and predictable across sessions. You can put it in your project's AGENTS.md or skill files and the agent always knows where to go.

The repo ships with skill files for both Cursor and OpenClaw-compatible agents, plus a dedicated AGENTS.md file. Vercel is explicitly signaling that dev tooling needs to treat AI agents as first-class consumers. That's a reasonable bet for where things are heading.

Installation and Setup

npm install -g portless

Global install, once. No per-project dependency needed.

# Run an app (proxy auto-starts)
portless myapp next dev

# Or use portless run to infer the name from your project directory
portless run next dev

# Check what's running
portless list

# Stop the proxy when done
portless proxy stop

Framework support: For frameworks that ignore the PORT environment variable (Vite, Astro, React Router, Angular, Expo), portless auto-injects the correct --port and --host flags. So you don't have to configure anything per-framework. It just works.

Static ports (Docker, etc.): If a service has a fixed port you can't change, use portless alias:

portless alias mydb 5432
# http://mydb.localhost:1355 now routes to port 5432

HTTPS Support

If you need HTTPS in local development (service workers, certain auth flows, etc.), portless has you covered:

portless proxy start --https

This enables HTTP/2 and generates certs automatically, prompting for sudo once to add the CA to your system trust store.

HTTP/2 is worth enabling beyond just HTTPS — browsers limit HTTP/1.1 to 6 connections per host, which bottlenecks dev servers that serve many unbundled files like Vite or Nuxt. HTTP/2 multiplexes all requests over a single connection.

Safari note: .localhost subdomains auto-resolve to 127.0.0.1 in Chrome, Firefox, and Edge. Safari relies on the system DNS resolver, which may not handle .localhost subdomains on all configurations. Fix it with:

sudo portless hosts sync

This adds your active routes to /etc/hosts so Safari plays nice.

Escape Hatch

Sometimes you need to bypass portless — maybe for a CI environment or a quick test:

PORTLESS=0 pnpm dev   # Runs your normal command, no proxy involved

Good escape hatch design. The tool doesn't trap you.

Where It Stands

Portless currently has around 3,000 GitHub stars and is actively maintained by Vercel Labs. It's worth noting this is coming from Vercel's experimental arm, not the core product team — so there's no guarantee of long-term Vercel platform integration. That said, the quality of the implementation and the pace of recent releases suggest this isn't vaporware.

Looking at the recent changelog: recent versions added per-hostname TLS certificates, proxy loop detection with proper 508 responses, and --force flag support for overriding conflicting routes. These are the kinds of edge cases that matter in real team environments, not just toy demos.

Should You Use It?

If you run a single project at a time on your local machine and rarely hit port conflicts, portless is probably overkill. Your friction level is low enough that the install isn't worth it.

If any of these apply to you, install it today:

• You run multiple services locally (frontend + API + workers + docs)
• You work in a monorepo
• You use AI coding agents (Claude Code, Cursor, Windsurf, etc.)
• You've ever lost session state because you restarted on a different port
• You want your browser history to be useful again

The integration cost is one npm install -g and a one-word addition to your dev script. The upside is real. Named, stable, human-readable local URLs are just better than port numbers, and the fact that it took this long for someone to build a clean solution to this is a little surprising in hindsight.

If you're already using Claude Code or another coding agent heavily, this one is a no-brainer. Give your agents stable URLs to work with and watch them make fewer port-related mistakes.

---

Portless is open source under the Apache-2.0 license. GitHub: vercel-labs/portless