Portless: Vercel Labs' Fix for the localhost Port Number Problem
A lightweight CLI tool that replaces port numbers with stable, named .localhost URLs. No more EADDRINUSE, no more memorizing port numbers, no more AI agents testing the wrong port. From the team behind Next.js.
Replace port numbers with stable, named .localhost URLs. For humans and agents.
Anyone who has worked on a multi-service project or a monorepo knows the pain: port 3000 is already in use, the API is on 8080 (or was it 3001?), your browser tab from yesterday is now showing a completely different app, and the AI coding agent you're working with just hardcoded the wrong port in its test command. Port numbers are an implementation detail that developers are forced to think about far too often.
Portless is a new tool from Vercel Labs that solves this with a simple idea: instead of localhost:3000, your app runs at myapp.localhost:1355. A lightweight local proxy assigns each dev server a stable, human-readable name that doesn't change between sessions.
// The Problem in Detail
The README lays out a comprehensive list of pain points that port-based local development creates, and they're all real issues that compound in larger projects.
// How It Works
Portless runs a local proxy daemon on port 1355 (configurable). When you prefix your dev command with portless <name>, it assigns your app a random port in the 4000-4999 range via the PORT environment variable, registers the name-to-port mapping with the proxy, and routes all requests from <name>.localhost:1355 to the actual port. Most frameworks (Next.js, Vite, etc.) respect the PORT env var automatically.
The proxy auto-starts when you run an app, so the typical workflow is just wrapping your existing dev command. Subdomains work too: portless api.myapp pnpm start gives you api.myapp.localhost:1355, which is useful for monorepo setups where you have a frontend, API, and docs all running simultaneously.
// Usage
| Command | Description |
|---|---|
portless <name> <cmd> | Run app at http://<name>.localhost:1355 |
portless list | Show active routes |
portless proxy start | Start the proxy daemon (port 1355) |
portless proxy start -p 80 | Start on port 80 (requires sudo) |
portless proxy stop | Stop the proxy |
PORTLESS=0 pnpm dev | Bypass proxy, use default port |
Integration into existing projects is a one-line change in package.json: replace "dev": "next dev" with "dev": "portless myapp next dev". The escape hatch is equally simple: set PORTLESS=0 or PORTLESS=skip to bypass the proxy entirely.
// The Agent Angle
This is arguably the most interesting aspect of Portless. 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.
The repo ships with skill files for both Cursor (.cursor/skills/) and OpenClaw-compatible agents (.agents/skills/), plus a dedicated AGENTS.md file. This is Vercel signaling that developer tooling needs to be designed with AI agents as first-class consumers, not just human developers.
// Technical Details
| Spec | Details |
|---|---|
| Runtime | Node.js 20+ |
| Platforms | macOS, Linux |
| Proxy Port | 1355 (configurable via -p or PORTLESS_PORT) |
| App Port Range | 4000-4999 (random assignment) |
| State (port ≥ 1024) | ~/.portless (user-scoped) |
| State (port < 1024) | /tmp/portless (shared, sudo required) |
| License | Apache-2.0 |
// Considerations
No Windows support. The tool currently only supports macOS and Linux. Windows developers are out of luck for now, though WSL2 may work (untested by the project).
No HTTPS. Everything runs over plain HTTP on localhost. For most local dev this is fine, but if you're testing HTTPS-dependent features (secure cookies, service workers, WebAuthn), you'll still need a separate solution.
Framework compatibility. The tool relies on frameworks respecting the PORT environment variable. Most popular frameworks (Next.js, Vite, Express, Fastify) do this automatically, but some tools may require additional configuration to pick up the assigned port.
Vercel Labs, not Vercel. This comes from Vercel's experimental lab, not the core product team. There's no guarantee of long-term maintenance or integration into the Vercel platform, though the 771 stars in a short time suggest strong community interest.
// Bottom Line
Portless solves a small but genuinely annoying problem in local development, and it does it with minimal complexity. The one-line integration, the escape hatch, and the "it just works with most frameworks" approach are all signs of good developer tooling design. The agent-first thinking is forward-looking: as AI coding agents become standard parts of the dev workflow, the tooling around them needs to provide stable, predictable interfaces. Named localhost URLs are a simple step in that direction.
For teams running monorepos, multiple microservices, or working heavily with AI coding agents, Portless is worth trying. It's a npm install -g and a one-line package.json change to evaluate.
