portless: The Death of Localhost Port Numbers
How vercel-labs/portless replaces volatile ports with stable, agent-friendly local domains.
- Portless replaces volatile port numbers with stable named domains to prevent state bleed and address-in-use errors.
- The tool uses process wrapping to inject ephemeral ports and framework-specific heuristics to automate routing.
- Stable local URLs provide a predictable infrastructure target for AI coding agents to execute autonomous testing loops.
- Integrated Git worktree detection automatically generates branch-specific subdomains for concurrent development.
The Localhost Sickness
Every developer knows the sting of an address-in-use error. For decades, local web development has relied on a shared, global namespace of four-digit port numbers. You start your frontend on port 3000. You start your backend on 3001. A colleague's project hardcodes 8080. When these numbers collide, the development environment breaks.
The problem runs deeper than simple collisions. Because browsers isolate cookies and local storage by domain rather than port, running multiple independent projects on a single localhost domain causes state to bleed across boundaries. A session token from a client project overwrites the authentication state of a personal side project. The developer experience degrades into a constant cycle of clearing local storage and manually incrementing environment variables.
"Portless from Vercel Labs replaces all of this with stable, named`.localhost` URLs.`localhost:3000` becomes`myapp.localhost`.`localhost:3001` for the API becomes`api.myapp.localhost`. Port numbers disappear."
The tool acts as a local reverse proxy and DNS management layer. It sits between the browser and various local development servers. It treats the port number as a low-level implementation detail that humans should never have to memorize.
Infrastructure for Agents
The shift to named local domains is not just about human ergonomics. It is a prerequisite for the emerging era of autonomous coding assistants. AI agents like Claude Code or Cursor rely on stable environments to write tests, verify changes, and execute browser automation.
When an agent spins up a local server, a dynamic port assignment creates a moving target. If the agent hardcodes port 3000 into a generated test suite, that test will fail the moment the port is occupied by another background process. Portless provides a stable, predictable routing target. The agent can confidently request a named host, knowing the proxy layer will handle the underlying ephemeral port mapping.
Portless by Vercel Labs replaces localhost port numbers with stable named URLs. Here's how it works, who it's for, and why AI coding agents care about it.
How Portless Hijacks the Process
The architecture of Portless centers on process wrapping. When a developer executes a standard start command through the tool, it intercepts the execution context. The CLI generates a random port number between 4000 and 4999. It injects this number directly into the environment variables of the child process.
Simultaneously, it registers this mapping in a file-locked route registry. The background proxy daemon watches this registry. When a browser requests the named local domain, the proxy inspects the host header and routes the traffic to the dynamically assigned port.
The system goes further than simple environment variable injection. Modern web frameworks often ignore standard port variables in favor of their own internal configuration files. Portless includes framework-specific heuristics. It detects tools like Vite, Expo, or Angular and automatically appends the necessary command-line flags to force compliance with the ephemeral port assignment.
Zero-Config Certificates and Git Worktrees
Modern frontend development requires HTTPS. Unbundled build tools rely on HTTP/2 multiplexing to serve thousands of individual JavaScript modules efficiently. Browsers strictly enforce security contexts, restricting certain web APIs to secure origins. Portless automates local TLS by managing its own local Certificate Authority.
It uses system-level utilities to generate a root certificate and automatically trusts it within the operating system keychain. Leaf certificates for individual projects are generated on demand. This provides a valid green lock in the browser with zero manual configuration.
The most powerful abstraction is its awareness of Git state. Portless detects when a project is running inside a Git worktree. It automatically prepends the current branch name as a subdomain. A developer can run the main branch and a feature branch simultaneously without port conflicts, accessing them via distinct, stable URLs.
The Proxy Graveyard
The concept of local DNS routing is not new. Developers have built workarounds for decades. However, previous solutions either lacked deep framework integration or required excessive manual configuration.
| Tool | Port Assignment | Zero-Config HTTPS | Git Worktree Routing | Framework Heuristics |
|---|---|---|---|---|
| Portless | Automatic (Ephemeral) | Yes | Yes | Built-in |
| Caddy | Manual configuration | Yes | No | None |
| Hotel (Legacy) | Manual or CLI-driven | Requires setup | No | None |
Production-grade proxies like Caddy handle TLS elegantly but require developers to maintain configuration files and manually manage port assignments. Legacy tools like Hotel provided named domains but failed to keep pace with the complexity of modern JavaScript monorepos. Portless succeeds by treating the local environment as a zero-configuration primitive, clearing the path for both human developers and autonomous agents.
Sources: