Portless
Deploying Portless in a team means managing local state, trust and startup
Plan a repeatable local-development rollout with explicit proxy settings, Node.js compatibility, certificate ownership and reversible service decisions.
What you will learn
- Define deployment as developer-machine integration
- Make persisted settings part of the rollout
- Treat persistent services as a separate approval
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
- A reproducible local rollout includes machine state, not just a package version.
- High ports and certificate trust solve different setup problems.
- Service installation and clean have system-level consequences.
Define deployment as developer-machine integration
For Portless, a deployment guide should first say where the software belongs: a development machine running local applications. The pinned package supports modern Node.js and includes Windows, macOS and Linux in its package metadata. That metadata is not evidence that every certificate store, shell, firewall and framework combination has been exercised by this article.
Choose whether the team owns a global installation or a project-local dependency. Project-local pinning makes a repository version explicit, but contributors may run different Portless versions across repositories while sharing local state. The README warns that this pre-1.0 state format can change. Include the CLI version and state directory in a troubleshooting record instead of assuming a working package lock explains the whole machine.
Make persisted settings part of the rollout
Automatic proxy startup reuses settings from the most recent proxy run. Explicit PORTLESS environment variables take priority. Therefore a restart is not a reset to HTTPS on 443, and a remembered LAN setting deserves particular attention. Write down scheme, proxy port, suffixes, LAN mode and state directory before changing a shared development environment.
Default HTTPS can generate and trust a local CA, while binding a privileged port may require elevation. Selecting a high port solves the port-binding issue but does not by itself solve certificate trust. A deliberate --no-tls exercise avoids that certificate path but changes the browser origin and security properties. Do not disable certificate verification globally to make an unexplained trust failure disappear.
Treat persistent services as a separate approval
The documented service installation writes launchd, systemd or Windows Task Scheduler configuration and can run as root or SYSTEM. This is materially different from an unprivileged foreground development process. Establish the executable path, service owner, startup options, logs and removal procedure before enabling boot-time startup; a successful HTTP request alone does not validate that lifecycle.
Use doctor to inspect health and service status to inspect an installed service. Avoid presenting clean as a harmless refresh: it removes Portless state, trust entries and managed hosts changes, and also removes its service. The review performed none of those machine changes. Its rollout acceptance checklist should be tested on a disposable machine before being applied to a shared developer workstation.
Implementation steps
- 1
Record Node, CLI version, state directory and existing proxy configuration.
- 2
Choose a local-only HTTP or approved HTTPS setup.
- 3
Verify named routing before proposing a persistent service.
- 4
Document recovery and ask before removing shared state or trust entries.
Copy-ready example
{
"rolloutChecklist": true,
"nodeMajorMinimum": 24,
"portlessVersion": "0.15.6",
"stateDirectory": "record actual path",
"proxyScheme": "choose explicitly",
"lanEnabled": false,
"systemServiceApproved": false,
"certificateTrustVerified": false
}Frequently asked questions
Can I just deploy it to my production server?
This series covers its documented development workflow, not a production ingress certification. Production availability, authentication and edge hardening require a separate design and validation.
Why did restarting preserve an unexpected setting?
The proxy intentionally reuses its previous configuration. Inspect persisted settings and explicit environment overrides rather than assuming restart restores defaults.
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