portless Release Notes

New Features

portless clean: New command stops the proxy if it is running, removes the local CA from the OS trust store when it was installed by portless, deletes allowlisted files under known state directories, and removes the portless-managed block from the hosts file. Custom --cert and --key paths are never removed. (#213)

Improvements

Hosts file sync by default: The proxy now keeps the hosts file in sync with active routes automatically (improves Safari and other setups where .localhost subdomains do not resolve to loopback). Set PORTLESS_SYNC_HOSTS=0 to opt out. The managed block is removed from the hosts file when the proxy exits. (#213)

Contributors

@ctate

New Features

LAN mode: New --lan flag exposes portless services to phones and other devices on the same network via mDNS .local hostnames. Auto-detects the active LAN IP, follows network changes, and supports --ip / PORTLESS_LAN_IP overrides for VPN or multi-interface setups. Publishes mDNS records with platform-native tools (dns-sd on macOS, avahi-publish-address on Linux). Adds *.local to generated certificate SANs so HTTPS works for LAN hostnames. (#168)

VitePlus support: Auto-inject --port for VitePlus (vp) dev server (#147)

Contributors

@gabimoncha

@carderne

New Features

Origin/Referer header rewriting: The proxy now rewrites Origin and Referer headers for portless-managed hostnames so backend CSRF protections accept proxied requests (#189)

Bug Fixes

Browser-blocked ports excluded from auto-selection: Ports that browsers refuse to connect to (e.g. 6666, 6667) are now excluded from automatic port assignment (#192)

State directory preserved during sudo elevation: Fix portless trust losing the state directory when elevating to sudo (#187)

Windows OpenSSL config detection: Auto-detect openssl.cnf location on Windows when OPENSSLDIR points to a non-existent path (#183)

Contributors

@ctate

New Features

Project dev dependency install: portless can now be installed as a project dev dependency (npm install -D portless) in addition to the global install. The npx/dlx guard now only blocks one-off downloads, not locally installed packages. (#179)

Bug Fixes

portless trust on fresh install: Fix portless trust failing on a fresh install when no CA certificate exists yet. The command now generates the CA and server certificates automatically before trusting. (#177)

Contributors

@ctate

Breaking Changes

HTTPS on port 443 is now the default: The proxy defaults to HTTPS on port 443 instead of HTTP on port 1355. Auto-elevates with sudo on macOS/Linux to bind privileged ports. Use --no-tls for plain HTTP on port 80, or -p 1355 for the previous unprivileged port. (#172)

PORTLESS_HTTPS env var inverted: HTTPS is on by default; set PORTLESS_HTTPS=0 to disable (replaces the old PORTLESS_HTTPS=1 opt-in). (#172)

New Features

HTTP-to-HTTPS redirect: When the HTTPS proxy runs on port 443, a companion HTTP server on port 80 automatically redirects all requests to HTTPS. (#172)

Auto-sudo for proxy lifecycle: portless proxy start auto-elevates with sudo when binding privileged ports. portless proxy stop does the same when the running proxy is owned by root. (#172)

Clean URLs: URLs are now https://myapp.localhost instead of http://myapp.localhost:1355. No port numbers to remember. (#172)

Contributors

@ctate

Breaking Changes

• Strict subdomain routing is now the default -- Subdomains no longer automatically match parent hostnames (e.g. api.myapp.localhost no longer routes to myapp.localhost). Use the --wildcard flag or PORTLESS_WILDCARD=1 env var to restore the previous behavior. (#158)

New Features

• --wildcard flag -- Opt in to wildcard subdomain routing where subdomains match registered parent hostnames. Configurable via PORTLESS_WILDCARD env var. (#158)

Bug Fixes

• Cert generation with dots in $HOME -- Fix TLS certificate generation failing when the home directory path contains dots (#157)
• DNS label limit for --name flag -- Fix regression where long --name values could exceed the 63-character DNS label limit (#144)
• Windows DEP0190 deprecation warning -- Silence Node.js deprecation warning on Windows by replacing shell: true with explicit cmd.exe /d /s /c spawning (#160)
• Windows duplicate PATH entries -- Deduplicate PATH environment variables in child process spawn on Windows (#155)

Improvements

• Removed chalk dependency -- Replaced chalk with lightweight ANSI color utilities to reduce install size (#170)
• Automated release process -- Added CI workflow for automated npm publishing and GitHub releases (#169)

Contributors

• @ctate
• @mynameistito