Portless
Portless quickstart: names, framework flags and a verifiable first request
Start with a named development app, distinguish proxy and app ports, and diagnose package scripts that cannot receive automatic framework flags.
What you will learn
- Start with a command you can explain
- Automatic injection has a deliberately narrow grammar
- Prove the route, then add convenience
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
- The proxy port and the assigned application port serve different purposes.
- Unclassified shell scripts are not silently rewritten.
- Use the actual listener and route table as evidence when diagnosing a failed request.
Start with a command you can explain
The upstream quickstart installs Portless and runs an explicit name followed by the development command, for example portless myapp next dev. This is an installation and local configuration action, not a read-only diagnostic. Review the selected package version, Node.js 24 requirement and first-run certificate permissions before running it on a work machine. The commands below are an opt-in example, not commands executed during this review.
For a less privileged HTTP exercise, start the proxy on port 1355 with TLS disabled, then launch a disposable application in a second terminal. The browser address includes :1355; this is the proxy port, not the dynamically assigned application port. Plain HTTP is useful for routing diagnosis but is not an equivalent test of Secure cookies, certificate trust or every browser capability.
Automatic injection has a deliberately narrow grammar
Portless sets PORT for child processes. For supported frameworks that need command-line options, cli-utils.ts adds a missing --port and sometimes --host. It distinguishes serving commands from operations such as builds and checks. A Vite build must not receive a development-server port just because its executable is recognized. Existing explicit port or host options also matter.
A package script containing an environment prefix, another script invocation, compound shell commands, a trailing comment or its own option terminator may be left unchanged. This prevents blindly appending arguments where they would affect the wrong command or become a comment. If the printed backend port and actual listener disagree, simplify the script or configure its port explicitly; do not repeatedly restart the proxy expecting a parser limitation to disappear.
Prove the route, then add convenience
Check portless list and use portless doctor for documented read-only health diagnosis. Confirm the application is running, then verify the exact scheme, name and proxy port in the browser. A proxy-generated 404 suggests no matching route; a 502 suggests the selected loopback backend could not be reached. Inspect the application output before treating either as a DNS failure.
After the explicit-name case works, consider portless run for inferred names and worktree prefixes. Keep the first test small enough to reverse: stop your disposable application and proxy without cleaning unrelated shared state. Our loopback library probe validates route behavior, not this entire installation flow or the framework-specific flag matrix on all operating systems.
Implementation steps
- 1
Review and install the chosen version only in an approved development environment.
- 2
Start an HTTP proxy on a nonprivileged port for the routing exercise.
- 3
Launch a disposable app with an explicit name in another terminal.
- 4
Check list, doctor and the exact URL before adding worktree automation.
Copy-ready example
# Optional setup example; not executed by this review
npm install -g portless@0.15.6
portless proxy start --no-tls --port 1355
# In a second terminal, inside a disposable Next.js project:
portless myapp next dev
# Open http://myapp.localhost:1355
portless list
portless doctorFrequently asked questions
Why did my package script keep its original port?
The injector may not recognize its syntax or may decline unsafe argument appending. Inspect the script and actual listener, and simplify or set its port deliberately.
Does the HTTP example prove HTTPS works?
No. HTTPS adds certificate generation, trust and browser validation. Test those separately after accepting their local configuration changes.
Sources
- README.mdSource checked 2026-09-08
- packages/portless/package.jsonSource checked 2026-09-08
- packages/portless/src/cli-utils.tsSource checked 2026-09-08
- packages/portless/src/proxy.tsSource checked 2026-09-08