Portless
Portless explained: stable local URLs without pretending ports disappear
Learn how Portless names development applications, what still listens on a port, and why local HTTPS, branch names and public sharing are separate decisions.
What you will learn
- The name is stable; the backend port is not the interface
- Choose a development identity deliberately
- Keep three kinds of evidence separate
Before you start
- Basic HTTP origins, ports and command-line concepts
- Ability to distinguish loopback, LAN and public exposure
Trace a named request, choose explicit setup boundaries and separate observed behavior from untested integrations.
Key takeaways
- Stable names hide port allocation from readers; they do not remove ports.
- A worktree hostname does not isolate every application resource.
- Local routing, certificate trust and remote exposure are separate boundaries.
The name is stable; the backend port is not the interface
Portless gives a development application a readable address such as https://shop.localhost. A local proxy receives the browser request, looks up the hostname and forwards it to a loopback application port. Ports still exist: the change is that people, browser bookmarks and development agents can use an application name instead of remembering whichever number was free.
Consider a frontend and an API that both default to port 3000. Changing one port fixes the immediate collision but may invalidate a callback URL or a copied test instruction. Named routes separate that human-facing identity from process allocation. They do not automatically rewrite application configuration, broaden CORS permissions or register an OAuth callback with an external provider.
Choose a development identity deliberately
The documented launcher assigns an available application port in the 4000–4999 range. Explicit names are useful for a first experiment; inferred names and linked-worktree branch prefixes help when several checkouts run together. A branch prefix is a routing identity, not proof that cookies, databases or credentials have been isolated between those checkouts.
At the inspected commit, package metadata reports version 0.15.6, Node.js 24 or newer and Apache-2.0 licensing. The CLI defaults to HTTPS, with local certificate generation and trust setup. The proxy can also serve HTTP on a chosen port. Those modes have different browser behavior and setup permissions; neither should be described as a zero-configuration guarantee on every machine.
Keep three kinds of evidence separate
This series follows fixed source files, not a moving README alone. A bounded experiment transpiled the inspected proxy modules without behavioral changes and passed 24 HTTP/1.1 cases using two disposable loopback backends. The cases cover routing, forwarded headers and the internal hosts-sync authorization path without actually modifying the operating system hosts file.
That experiment did not install the CLI, trust a certificate, open a public tunnel, exercise HTTP/2 or validate a framework HMR session. Treat those as documented features requiring their own integration checks. A useful first success condition is narrower: the expected name reaches the expected application, an unknown name fails, and stopping the application has an understood result.
Implementation steps
- 1
Write down one application name and its expected backend.
- 2
Check Node.js compatibility and choose HTTP or HTTPS deliberately.
- 3
Inspect the active route and request the named URL.
- 4
Record untested browser, framework and sharing features separately.
Copy-ready example
{
"example": "conceptual routing, not a configuration file",
"browserOrigin": "https://shop.localhost",
"routeName": "shop.localhost",
"backend": "127.0.0.1:<allocated-port>",
"portsStillExist": true
}Frequently asked questions
Is Portless a production hosting platform?
Its documented workflow is local development routing. These tests do not qualify it as a production ingress or provide a production deployment recipe.
Does a stable name fix CORS automatically?
No. CORS, cookies and callback allowlists belong to application and provider configuration. Changing the origin can require explicit updates.
Sources
- README.mdSource checked 2026-09-08
- packages/portless/package.jsonSource checked 2026-09-08
- LICENSESource checked 2026-09-08
- packages/portless/src/proxy.tsSource checked 2026-09-08