Access local development servers by name instead of port number
Enter an app name in the browser address bar instead of a number, and keep the same address after restarts. This tool assigns a unique name to each development server via a local reverse proxy, ensuring that bookmarks, cookies, OAuth redirects, and AI agent test scripts always point to the correct app.
Structure that eliminates port conflicts and memory load
portless runs a local reverse proxy to assign names to each development server. Apps run on a random port between 4000 and 4999 assigned by portless, and users access them via the https://<name>.localhost address. This address remains unchanged after restarts, preserving bookmarks and session state. For frameworks like Vite, Astro, Angular, Expo, and Wrangler that do not directly read the PORT environment variable, portless automatically adds the necessary port and host flags to the command line.
Automatic handling of HTTPS and DNS
On first run, portless creates a local Certificate Authority (CA) and adds it to the system trust store. This process may require sudo privileges, though you can use plain HTTP with the --no-tls option or skip sudo with --unprivileged mode. The proxy listens only on 127.0.0.1 and ::1 by default and synchronizes the /etc/hosts file to ensure custom TLDs like .test are interpreted correctly. If a route hostname does not resolve, it warns you to run the portless hosts sync command.
Collaboration with AI agents
portless provides an MCP server that allows AI agents to control the local development environment. Running the portless mcp command starts the MCP server via stdio, with the default core profile supporting route list queries, URL search, and static alias management. Adding the --tools all option enables proxy control and diagnostic features. Agents do not start development servers directly through this server; instead, they run portless run <cmd> in the shell to launch apps.
Things to check before use
portless runs on Node.js 24 or higher on macOS, Linux, and Windows. As it is currently a pre-1.0 version, the state directory format may change between releases, which might require re-running portless trust. Accessing or sharing apps from other devices requires Tailscale, ngrok, or the Cloudflare quick tunnel CLI to be installed. If a URL does not load, run the portless doctor command first to check the status of the proxy, routes, DNS, and CA trust, and review any suggested fixes.
