Ports 4000 through 4999 become stable local names
Portless starts each application on a free port between 4000 and 4999, then routes a name such as https://api.myapp.localhost to it. The application receives PORT, HOST, and PORTLESS_URL variables, while the browser and teammates use the memorable address. That removes port collisions from daily conversation and gives local cookies, redirects, and WebSocket clients a hostname that survives restarts.
Framework handling goes beyond setting 1 environment variable. Portless injects port and host flags for Vite, Astro, Angular, Expo, React Native, and other servers that ignore PORT. A monorepo can start all workspace packages with dev scripts, and Git worktrees receive a branch-derived subdomain. That is particularly useful for parallel agents, since 2 checkouts can stay open without sharing one callback URL.
Port 443 requires local trust and often administrator rights
HTTPS and HTTP/2 are enabled by default on port 443. On the first run, Portless creates a local certificate authority, installs it in the operating system trust store, and may request sudo on macOS or Linux. Plain HTTP uses port 80, while an unprivileged custom port avoids sudo at the cost of keeping a port number in the URL.
Those changes are visible and reversible, but they belong to the whole machine. State is stored under the user's .portless directory, route hostnames may be written to the hosts file, and the clean command removes the state, trust entry, and managed hosts block. A startup service can be installed through launchd, systemd, or Windows Task Scheduler. That service can run with root or SYSTEM rights, so teams should treat installation as workstation configuration rather than a package-script detail.
What happened when we ran it
Our sandbox installed commit 1ad573b in 51 seconds. Pnpm added 1,527 packages and the installed tree occupied 1,061 MB. The build then completed successfully in 45 seconds. The repository itself had 196 files, about 31,661 lines of source, and a 2.2 MB checkout.
Vitest finished in 83 seconds with 931 passed, 0 failed, and 3 skipped out of 934. That is a complete passing result for the tests the project exposed in our fresh environment. The repository had a tests directory and 2 CI workflow files, which matches the unusually detailed edge-case coverage visible in its documentation.
Our test method used an unprivileged Debian container with 3 CPUs, 8 GB of RAM, Node.js 22, and no secrets. Install, build, and tests all succeeded there at the measured commit. The current development section now asks contributors to use Node.js 24+ and pnpm 11, so the older successful runtime is evidence about our commit, not a promise that future releases support Node.js 22.
Version 0.15.6 leaves complex package scripts alone
Version 0.15.6 improved flag injection through supported package-manager scripts, but classification remains intentionally conservative. Compound commands, trailing comments, option terminators, environment prefixes, delegated scripts, and runner flags before the script name keep their own ports. This avoids breaking commands Portless cannot parse safely. It also means a project with an elaborate dev wrapper may need an explicit appPort or a simpler script dedicated to the server.
Default .localhost names work in most browsers, while Safari may need a hosts sync. Google and Apple reject .localhost and .test for strict OAuth callbacks, so the README supports a domain you own as a custom multi-segment TLD. Portless writes the required loopback mapping and still binds locally. LAN mode is a separate path that switches to .local and mDNS; on Linux it requires avahi-utils, and a custom TLD cannot be combined with LAN mode today.
121 open items include route-state and Docker gaps
GitHub listed 121 open issues and pull requests on September 2, 2026. Issue 382 describes route-state corruption when an IDE force-kills a process during cleanup and an in-place routes.json write is interrupted. The report says other running routes can disappear with the damaged file. This is a specific failure mode, but IDE stop buttons and process managers make it plausible enough to test before a team puts every local service behind one shared route store.
Docker integration is still partial. Issue 110 requests native Compose support, while issue 399 reports host-gateway refusal because the normal proxy binds only to 127.0.0.1 and ::1. Portless can alias a fixed container port, yet teams expecting label discovery or a non-LAN wildcard bind will find Traefik or Caddy easier to fit.
August 2026 activity supports a careful workstation trial
The last source push was August 29, 2026, and v0.15.6 shipped on August 24. Issue discussion continued into September, so the 121-item combined queue is active rather than abandoned. The release fixed Windows service lifetime, Ctrl+C cleanup, and framework flags, all close to the system-level boundaries that can make a local proxy annoying.
Portless earns a trial when stable HTTPS names solve a repeated problem across several services or worktrees. The 931 passing tests lower the code-risk concern, while 1,061 MB of dependencies and machine-level trust changes raise the setup cost. Start it on one repository, verify HMR, cookies, sibling TLS clients, IDE shutdown, and cleanup, then decide whether replacing port numbers is worth owning the shared proxy.