portless Updates & Release Notes

Bug Fixes

Multi-segment custom TLDs: --tld and PORTLESS_TLD now accept dotted DNS names such as dev.example.com, so local URLs can mirror production structure. validateTld checks per-label DNS rules and the 253-character total limit, overlapping TLDs resolve by longest match, and cert cache filenames stay under the filesystem name limit for long hostnames. (#365)

WebSocket over HTTP/2: Proxy now advertises RFC 8441 extended CONNECT and bridges :protocol websocket streams to an HTTP/1.1 upgrade against the backend, fixing dev server HMR for browsers that negotiate h2 over ALPN. Plain-HTTP upgrades on the TLS port are proxied instead of dropped, and a backend that rejects the handshake or answers with a bad Sec-WebSocket-Accept now gets a 502 instead of a silently destroyed socket. (#363)

Contributors

@Railly

@KingPsychopath

@erichurkman

@sanjevirau

Bug Fixes

State directory under sudo: Portless now resolves per-user state from the original sudo user's home, so an elevated proxy and unprivileged app processes share the same routes instead of writing to separate state directories. (#357)

Windows and WSL CA trust: On WSL, portless trust now installs the local CA in both Linux and Windows trust stores, while portless clean removes the exact certificate from both. Failed trust-store cleanup preserves the CA identity for safe retries, including on native Windows. (#357)

Contributors

@ctate

@gerardbalaoro

Bug Fixes

Tailscale funnel routing: Proxy now routes requests addressed to a route's Tailscale funnel or serve hostname, so --funnel and --tailscale apps reached at <device>.ts.net no longer return a 404, including when several apps share one hostname on different ports. (#352)

IPv6-only dev servers return 502: Proxy now dials upstreams over both loopback families, fixing 502s when a dev server binds ::1 only, such as Vite on Node 17+. (#353)

Worktree prefix in multi-app mode: Bare portless in a monorepo worktree now applies the branch prefix in multi-app mode as it already did for single apps, so hostnames no longer collide across worktrees. (#355)

Contributors

@Railly

@ahfoysal

New Features

portless doctor: New read only diagnostics command checks Node.js, the state directory, proxy liveness, route entries, hostname resolution, HTTPS CA trust, and LAN prerequisites, then prints suggested fixes. (#337)

Bug Fixes

HTTP/2 Host forwarding: Proxy now forwards HTTP/2 :authority as Host to HTTP/1.1 backends, fixing apps that depend on Host and previously saw 127.0.0.1 for browser traffic. (#328)

--force takeover cleanup: Exit cleanup now removes only routes still owned by the exiting process, so a forced takeover does not deregister the new owner's route. (#328)

Contributors

@ctate

New Features

ngrok sharing: New --ngrok flag exposes portless apps publicly through ngrok while keeping the local .localhost URL. Also configurable with PORTLESS_NGROK=1; child processes receive PORTLESS_NGROK_URL, and portless list shows active ngrok URLs. (#323)

Improvements

ngrok tunnel lifecycle: Portless now checks for the ngrok CLI before starting an app, surfaces install and authentication guidance, removes stopped ngrok URLs from route state, and terminates tunnel processes during app cleanup. (#323)

Contributors

@ctate

New Features

Configurable startup services: portless service install now persists proxy options such as --port, --no-tls, --lan, --ip, --tld, --wildcard, --cert, --key, and --state-dir into launchd, systemd, and Task Scheduler. portless service status now reports the installed service port, HTTPS mode, TLD, LAN mode, wildcard mode, and state directory.

Bug Fixes

Service reinstall port changes: Reinstalling the startup service with a different port now stops any existing proxy on the previous port before starting the new service.

Service install validation: LAN service installs now fail early on platforms that cannot publish mDNS records, and service paths such as ~ are normalized before writing native service files.

Requirements

Node.js 24: The published package now requires Node.js 24 or newer, and repository development uses pnpm 11 with a minimum release age policy. (#307)

Contributors

@ctate

@skaldebane

@ItalianScallian

@neefrehman

New Features

OS startup service: New portless service install, portless service status, and portless service uninstall commands manage a native startup service for the HTTPS proxy across macOS launchd, Linux systemd, and Windows Task Scheduler. The service starts clean .localhost URLs after reboot, and portless clean removes it during cleanup. (#289)

Bug Fixes

Tailscale readiness preflight: --tailscale and --funnel now check Tailscale HTTPS and Funnel prerequisites before starting the child process, surfacing actionable errors instead of hanging during registration. (#282)

Contributors

@ctate

@Anshuman71

New Features

Tailscale sharing: New --tailscale flag shares any portless app over your Tailscale network with zero framework config. Each app is root-mounted on its own Tailscale HTTPS port (443, 8443, 8444, ...) so no basePath configuration is needed. Works as a global flag, per-app flag (portless myapp --tailscale next dev), or env var (PORTLESS_TAILSCALE=1). (#262)

Tailscale Funnel: New --funnel flag exposes apps to the public internet through Tailscale Funnel. Implies --tailscale. Also configurable via PORTLESS_FUNNEL=1. (#262)

PORTLESS_TAILSCALE_URL env var: Child processes receive PORTLESS_TAILSCALE_URL containing the Tailscale HTTPS URL so apps can reference their public address. (#262)

Tailscale URLs in portless list: The list command now shows tailnet URLs alongside local URLs when Tailscale sharing is active. (#262)

Improvements

portless prune cleans stale Tailscale registrations: Prune now removes orphaned tailscale serve entries left behind by dead CLI sessions. (#262)

portless clean removes Tailscale serve state: Clean now tears down any Tailscale serve/funnel registrations alongside the usual CA and hosts file cleanup. (#262)

Contributors

@ctate

New Features

portless prune command: Safety net to find and kill orphaned dev servers left behind by dead CLI sessions. Reads stale route entries, checks if something is still listening on each port, and terminates the orphan.

Bug Fixes

Zombie process orphaning on CLI crash: Spawn child processes with detached:true on Unix so they get their own process group. Signal handlers now kill the entire group instead of just the immediate child, preventing orphaned dev servers from surviving CLI crashes or kill -9.

Contributors

@ctate

New Features

Zero-arg mode: Run bare portless from any project directory to auto-discover the dev script from package.json and start it through the proxy. No arguments, no config required. (#251)

Multi-app orchestration: In monorepos, bare portless auto-discovers workspace packages (pnpm, npm, yarn, bun) and starts all dev scripts concurrently through the proxy. Each package gets a subdomain derived from its npm scope (e.g. @acme/docs becomes docs.acme.localhost). (#251)

Turborepo integration: When turbo.json is present, portless delegates to turbo run <script> instead of spawning each app individually. Per-app PORT, HOST, and PORTLESS_URL are injected via a lightweight --require loader so turbo retains dependency ordering and task graph awareness. Set turbo: false in config to opt out. (#251)

portless.json config file: Configure app name, script, port, and turbo settings without embedding portless in package.json scripts. Also supports a "portless" key in package.json as an inline alternative. (#251)

--script flag: Override the default "dev" script for a single invocation (e.g. portless --script start). (#251)

Rsbuild support: Auto-inject --port and --host CLI flags for Rsbuild dev server (#250)

Bug Fixes

State directory moved to ~/.portless: All proxy state now lives in ~/.portless instead of /tmp/portless, fixing repeated CA trust prompts on macOS (where /tmp is periodically cleaned) and a symlink local privilege escalation vulnerability (#251)

Duplicate macOS CA certificates: Fix security delete-certificate failing with "is ambiguous" when multiple portless CA entries had accumulated in the keychain (#251)

CA trust marker caching: Cache the CA fingerprint after a successful trust so subsequent proxy starts skip the OS security check and avoid re-triggering the macOS authentication dialog (#251)

Improvements

Auto-trust CA on proxy auto-start: When the proxy is auto-started and the CA is not yet trusted, portless automatically runs trust with proper sudo elevation (#251)

Package manager delegation: Detects pnpm, yarn, bun, or npm and delegates script execution to the correct package manager (#251)

Non-server script detection: Build-only tools (tsup, tsc, esbuild, etc.) are auto-detected and run without a proxy route. Use proxy: false in config for explicit control. (#251)

Monochrome CLI output: Bold for headers and errors, dim for warnings and muted text, no color codes (#251)

Contributors

@ctate

New Features

Auto-inject NODE_EXTRA_CA_CERTS: Child processes spawned by portless run now automatically receive NODE_EXTRA_CA_CERTS pointing to the portless CA certificate, so Node.js subprocesses trust the local CA without manual configuration (#220)

Bug Fixes

Proxy startup on slow macOS security command: Fix the proxy failing to start when the macOS security command takes longer than expected to verify CA trust (#229)

Lock contention with parallel commands: Fix lock contention that could cause failures when multiple portless commands run simultaneously (#230)

ERR_HTTP2_PROTOCOL_ERROR during HMR: Fix HTTP/2 stream reset flood during hot module replacement causing protocol errors (#231)

Proxy auto-start in non-interactive terminals: Fix auto-start failing in non-interactive terminals (e.g. IDE task runners) and when previous proxy config exists (#232)

Contributors

@ctate

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