Skip to content
Search

Portless

lastmod 2026-03-02created 2026-03-021 edits

A tool that replaces port numbers with name-based .localhost URLs

About

  • An open-source utility from Vercel Labs that solves the pain of port conflicts and having to remember which port you used during local development
  • Gives each dev server a unique app.localhost subdomain, providing a URL scheme that both humans and AI agents can recognize
  • Running next dev gives you http://localhost:3000, so you have to remember 3000, but
  • running portless myapp next dev makes it accessible in the form http://myapp.localhost:1355
  • Running something like portless api.myapp pnpm start also supports subdomain access via http://api.myapp.localhost:1355
  • Works on a proxy-based architecture, with portless proxy routing requests centrally
    • The proxy starts automatically when an app runs, and each app is assigned a random port (4000–4999)
    • Most frameworks (Next.js, Express, Nuxt, etc.) automatically recognize the PORT environment variable
    • Some frameworks such as Vite and Astro get compatibility through automatic flag injection
  • HTTP/2 and HTTPS support for fast page loads and secure local communication
    • Automates self-signed certificate generation and registration in the system trust store
    • Custom certificates can also be applied with the --cert and --key options
  • Provides a command-oriented CLI interface
    • portless <name> <cmd> : run an app under the given name
    • portless list : show the list of active routes
    • portless proxy start/stop : control the proxy
    • The PORTLESS=0 environment variable lets you run bypassing the proxy
  • Stores route and PID information in a state management directory
    • Uses ~/.portless in normal user mode and /tmp/portless in root mode
    • The path can be overridden with PORTLESS_STATE_DIR
  • When configuring an API proxy in Vite, webpack-dev-server, etc., the Host header must be rewritten
    • A misconfiguration is flagged with a 508 Loop Detected response
  • Supports Node.js 20 or later on macOS and Linux
  • Monorepo structure based on pnpm + Turborepo
  • Apache-2.0 license, TypeScript (about 74%) codebase

See also

Favorite site

author Zer0 sitemap