* feat: add portless doctor
- Add read-only health diagnostics for proxy, routes, DNS, CA trust, and LAN prerequisites
- Document the doctor command in CLI help, README, docs, and the portless skill
- Cover doctor behavior with focused CLI tests
* fix: harden doctor diagnostics
* fix: handle custom certs in doctor
* Fix doctor diagnostics edge cases
* Fix doctor nested state directory check
* chore: require pnpm release age policy
- Add pnpm minimum release age 2880 and deny dependency build scripts.
- Require Node 24 and pnpm 11 across engines, CI, and version files.
- Refresh docs and lockfile for the runtime upgrade.
* ci: install pnpm after node setup
- Put Node 24 on PATH before pnpm/action-setup installs pnpm 11.
- Keep setup-node cache restore after pnpm is installed.
* ci: run javascript actions on node 24
- Opt CI and release workflows into GitHub JavaScript action execution on Node 24.
- Unblock pnpm/action-setup from installing pnpm 11.
* ci: avoid engine strict pnpm setup
- Remove the root engine-strict npm config.
- Drop the temporary Node 24 JavaScript action runtime override.
* test: use valid ca pem fixture
- Replace the fake CA text used in NODE_EXTRA_CA_CERTS tests with a valid PEM.
- Avoid Windows Node 24 aborting before the capture script runs.
* Add OS startup service support
Install a native startup service for the HTTPS proxy so clean localhost URLs are available after reboot without repeated sudo prompts.
* Harden service support and integrate with portless clean
- Change requireUnixElevation return type from boolean to void
- Switch macOS KeepAlive to unconditional restart
- Wrap ensureCerts with actionable error message mentioning OpenSSL
- Escape percent signs in Windows batch env values
- Make portless clean uninstall the startup service before removing state
- Add tests for KeepAlive, percent escaping, and tryUninstallService
- Document that portless clean removes the service automatically
* Fix hardcoded task name in tryUninstallService and add handleService tests
Use spec.taskName instead of a literal string in the Windows branch of
tryUninstallService so the query stays consistent if the constant changes.
Add unit tests for handleService dispatch: help output, no-subcommand
help, and unknown subcommand error exit.
* Fix implicit any in service test mock.calls map callbacks
* Fix flaky tryUninstallService test on machines without service installed
Mock fs.existsSync so the runner is actually invoked regardless of
whether the service file exists on the test machine.
* Fix Windows CI failures in service tests
Use path.posix.join for macOS/Linux paths so they produce forward
slashes regardless of the build platform. Fix the "not installed" test
to use a non-zero runner status so it works on win32 (where the code
path checks schtasks query status rather than fs.existsSync).
* Fix startup service lifecycle ownership
Ensure service installation takes over any existing proxy and make clean elevate when protected service entries need removal.
* Fix service uninstall runner error test
* Fix service clean elevation and Windows PATH
Keep clean running in the original user context after elevated service removal, and preserve PATH for Windows startup tasks so runtime OpenSSL lookups work.
* Add Tailscale sharing and Funnel support
Add --tailscale and --funnel flags that let any portless app be shared
over Tailscale with zero framework config. Each app is root-mounted on
its own Tailscale HTTPS port (443, 8443, 8444, ...) so no basePath
configuration is needed.
- New tailscale.ts module with readiness checks, port allocation,
serve/funnel registration, and injectable TailscaleCommandRunner
for testing
- --tailscale / --funnel flags work as global flags, per-app flags
(portless myapp --tailscale next dev), and env vars
(PORTLESS_TAILSCALE=1, PORTLESS_FUNNEL=1)
- Tailscale readiness is checked before proxy auto-start so failures
are reported immediately with actionable messages
- portless list shows tailnet URLs alongside local URLs
- portless prune and portless clean remove stale tailscale serve
registrations
- PORTLESS_TAILSCALE_URL injected into child process environment
- RouteMapping extended with optional tailscale metadata
- 41 new tests covering the tailscale module, CLI flags, and route
metadata persistence
* fixes
* fixes
Spawn child processes with detached:true on Unix so they get their own
process group. Signal handlers now kill the entire group via
process.kill(-pid) instead of just the immediate child, preventing
orphaned dev servers from surviving CLI crashes or kill -9.
Add `portless prune` command as a safety net to find and kill orphaned
dev servers left behind by dead CLI sessions. It reads stale route
entries, checks if something is still listening on each port, and
terminates the orphan.
Add e2e tests covering both the SIGKILL cleanup path and the prune
command.
* Add portless.json config file and zero-arg mode
Adds an optional portless.json for configuring app name, script, and
port without embedding portless in package.json scripts. Running bare
`portless` from a workspace root auto-discovers pnpm packages and
starts all dev scripts concurrently through the proxy. The --script
flag overrides the default "dev" script for a single invocation.
* Use npm scope as project base for multi-app names
In multi-app mode, package names are now composed as subdomains of the
npm scope (e.g., @og-sdk/docs becomes docs.og-sdk.localhost). Falls
back to inferring the project name from the workspace root when
packages are unscoped.
* Pass through scripts that already invoke portless
In multi-app mode, if a package's dev script starts with `portless`,
run it as-is without registering a route or injecting PORT/HOST. The
embedded portless invocation handles its own name and routing.
* Fix multi-app PATH and deduplicate project name
Augment PATH with node_modules/.bin from each package's directory so
local binaries (tsup, next, vite, etc.) are found. Skip the project
suffix when the package name already matches it (avoids names like
portless.portless).
* Fix proxy start prompting for trust on every launch
Cache the CA fingerprint in a marker file (ca.trusted) after a
successful trust so subsequent proxy starts skip the OS security
check and avoid re-triggering the macOS authentication dialog.
Also switch docs and example dev scripts to clean "next dev".
* Skip proxy route for build-only tools, support portless config in package.json
Non-server commands (tsup, tsc, esbuild, etc.) are auto-detected and
run without a proxy route. Adds "proxy" config field for explicit
control. Also supports a "portless" key in package.json — either as
an object or a string shorthand for the app name.
* Address PR review: config fixes, proxy auto-start, and refactors
- Rewrite splitCommand to respect quoted arguments
- Use frequency count for commonScope instead of first match
- Extract ensureProxyRunning helper; call from multi-app mode
- Remove loadConfig directory walk-up (check cwd only)
- Deduplicate clearTrustMarker call in generateCA
- Remove proxy field from config (system-level, not app-level)
- Fix early script filter to respect per-app overrides
- Add portless key to google-oauth example
- Replace invalid JSON comments with markdown headings in docs
- Extract spawnProxiedApp/spawnTaskApp helpers from handleDefaultMulti
* Address PR review: docs fixes, config precedence, proxy option
- Fix docs claiming config walks up directories (it does not)
- Clean up resolveAppConfig to use explicit field return
- Add JSDoc to isServerCommand explaining denylist design
- Add comment on sequential proxy spawning (port collision)
- Handle backslash escapes in splitCommand
- Remove non-null assertion on discovered proxy state
- Pass appConfig through to avoid redundant disk read
- Fix config precedence: package.json portless key wins (closest)
- Implement proxy: false config option for non-server scripts
* Add package manager delegation, turborepo support, and fix TLS state discovery
- Add detectPackageManager and resolveScriptCommand to delegate script
execution to the correct package manager (pnpm/yarn/bun/npm) instead
of parsing shell scripts directly. This enables reliable turborepo
integration where `portless` is the dev script.
- Fix discoverState inferring tls=false when the proxy is running on
port 443 but state files in /tmp were cleaned by the OS.
- Re-discover proxy state in multi-app mode when proxy is already running.
- Add turborepo integration docs and tests.
* Address PR 251 review: child lifecycle, shell safety, line buffering, proxy dedup, multi-PM workspaces, config errors
- Log exit codes per child and print summary in multi-app mode
- Spawn child processes directly without shell for PM-delegated commands
- Buffer partial lines in prefixed output streams, flush on end
- Extract resolveProxyDesiredState helper to deduplicate proxy config
- Support npm/yarn/bun workspaces via package.json "workspaces" field
- Replace process.exit in config validation with ConfigValidationError
* Address PR review: SIGKILL fallback, YAML flow sequences, glob wildcards, stream fixes
- Add 5s SIGKILL timeout after SIGTERM in multi-app cleanup to prevent
hanging when children ignore SIGTERM
- Handle YAML flow sequence syntax (packages: [a, b]) in pnpm workspace
parser, with JSDoc documenting the supported YAML subset
- Fall through from multi-app to single-app mode when no workspace
packages have the target script, so workspace roots with their own
portless.json still work
- Refactor expandSingleGlob into recursive expandSegments to support
mid-path wildcards (packages/*/src) and prefix wildcards (apps/team-*)
- Use StringDecoder in prefixStream for correct multi-byte UTF-8 handling
across chunk boundaries, and preserve empty lines from child output
* Eliminate /tmp state dir, fix symlink LPE, and clean up multi-app output
Move all proxy state from /tmp/portless to ~/.portless, fixing both the
macOS /tmp cleanup problem (repeated trust prompts) and the symlink LPE
vulnerability (GHSA-p67g-wf2j-g3h5). Add lstatSync symlink guard in
fixOwnership as defense-in-depth. Remove the interactive "Start proxy?"
prompt in favor of auto-starting. Rewrite multi-app startup output so
URLs stand out clearly. Also addresses PR 251 review items: re-throw
ConfigValidationError, fix splitCommand backslash handling in single
quotes, warn on unknown config keys, and remove unused export.
* Fix macOS CA cleanup when multiple certs share the same CN
Loop delete-certificate calls to remove all matching "portless Local CA"
entries from each keychain. The previous single call failed with
"is ambiguous, matches more than one certificate" when duplicate CAs
had accumulated from repeated trust prompts.
* Auto-trust CA after proxy auto-start
When the proxy is auto-started in single-app or multi-app mode and the
CA is not yet trusted, run handleTrust which has proper sudo elevation
logic. This prevents the scenario where a new user cancels the trust
dialog during proxy start and is left with browser cert errors and no
clear recovery path.
* Fix prettier formatting in configuration docs
* Use turbo for multi-app orchestration
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, output grouping, and task graph awareness.
Falls back to direct spawning when turbo is absent or when the config
sets `"turbo": false`.
* Fix turbo loader double-escape, cleanup guards, and direct-spawn route cleanup
- Remove redundant manual backslash escape in loaderSource; JSON.stringify
already handles escaping for JS string literals
- Quote loader path in buildNodeOptions when it contains spaces
- Add cleanedUp guard to runWithTurbo and runWithDirectSpawn cleanup
functions to prevent double execution on signal + explicit call
- Strip trailing \r in prefixStream so Windows \r\n output renders cleanly
- Track routes in runWithDirectSpawn and remove them in the signal handler,
matching the pattern already used by runWithTurbo
* Fix doc gaps: state dir, CA path, turbo field, pkg portless key, hostname convention
- State directory docs still showed the old 3-tier table (port < 1024
-> /tmp/portless). All state now lives in ~/.portless; updated
SKILL.md and docs configuration page.
- CA path references in README and SKILL.md still mentioned
/tmp/portless/ca.pem; simplified to ~/.portless/ca.pem.
- Added the `turbo` config field to all three config tables.
- Documented the package.json "portless" key as a standalone feature
(was only shown in the Turborepo section).
- Documented the multi-app hostname convention
(<package>.<project>.localhost derived from common npm scope).
* Make bare portless just work everywhere, monochrome output
- Remove config gates: bare `portless` and `portless run` resolve the
dev script from package.json without requiring portless.json
- Extend PORTLESS=0 skip path to handle zero-arg mode
- Monochrome CLI output: bold for headers/errors, dim for warnings/muted,
no color codes
- Multi-app display: show full package name (with scope), alphabetized,
URLs dimmed
- Update docs, help text, and tests to reflect zero-config defaults
* Improve multi-app output and turbo integration
- Show full scoped package names in startup list, alphabetized
- Hide task-only packages from output (they still run)
- Use root package.json dev script for turbo when available,
preserving user's flags like --concurrency and --filter
- Pass extra args after -- through to turbo
* Restore red/yellow ANSI colors for errors and warnings
- Non-interactive environments (no TTY, CI=1) now exit with a clear error instead of prompting, so task runners like turborepo fail early with manual start instructions (#224)
- Auto-start reads persisted state files (proxy.port, proxy.tls, proxy.tld, proxy.lan) so a reboot does not silently revert to default configuration; explicit env vars and flags still take priority (#225)
- Fix discoverState() fallback to read TLS/TLD markers from disk instead of hardcoding tls:false and the default TLD
Closes#224, closes#225
* Automatically inject NODE_EXTRA_CA_CERTS for child processes
Fixes Node.js server-side fetches failing with "self-signed certificate in certificate chain" when making HTTPS requests to portless-proxied services.
## Problem
Node.js uses its own hardcoded CA bundle and ignores the system trust store. When server-side code (like Next.js Server Components) makes fetch requests to portless HTTPS URLs, Node.js rejects the portless CA as untrusted, even though browsers work fine.
## Changes
- Automatically inject `NODE_EXTRA_CA_CERTS` pointing to the portless CA cert when spawning child processes
- Only set when TLS is active and user hasn't already configured it
- Added comprehensive tests covering TLS enabled/disabled and user override scenarios
- Updated documentation to reflect automatic injection
## Implementation
The fix adds the CA cert path to the child process environment alongside existing variables like `PORT`, `HOST`, and `PORTLESS_URL`. This tells Node.js to trust the portless CA in addition to its built-in certificate bundle.
Fixes#218
* Fix CI: use script files for CA cert tests, show var in log line
- Write capture script to a file instead of using `node -e` with inline
JS, fixing cmd.exe quoting failures on Windows
- Extract runWithMockProxy helper to deduplicate test setup
- Move caEnv computation before the Running: log line so
NODE_EXTRA_CA_CERTS is visible in the status output
* Address review feedback on NODE_EXTRA_CA_CERTS injection
- Quote the CA path in the Running: log line to handle spaces
- Add test for ca.pem missing (exercises the fs.existsSync guard)
- Add comment noting process.env coupling for future-proofing
* update expo injected args, implement --lan flag for portless using mDNS
* enhance expo docs and add --lan flag docs
* update skills and readme
* fix nextjs allowedDevOrigins example
* persist proxy config, follow LAN IP changes, and fix Expo host handling
* implement proxy.lan for sticky lan config
* implement PR review
* fix lan-ip.test.ts type check
Previously `--force` only replaced the route entry on disk without
terminating the existing process, so the old server kept running and
held its port. Frameworks like Next.js would then refuse to start
("Another server is already running").
`addRoute()` now sends SIGTERM to the conflicting process when
`force` is true, and the CLI logs which PID was killed.
Fixes#201
Co-authored-by: ctate <366502+ctate@users.noreply.github.com>
* Rewrite Origin/Referer headers in proxy for portless-managed hostnames
- Frameworks like Next.js 16.2+ block cross-origin requests to dev endpoints (e.g. /_next/webpack-hmr) when the Origin header doesn't match their allowlist. Next.js auto-allows *.localhost, but * only matches a single subdomain level, so multi-level names like admin.cmd.localhost are blocked.
- The proxy now rewrites Origin and Referer headers to http://localhost:{port} when the hostname belongs to the portless TLD. The original host is preserved in X-Forwarded-Host.
- This is framework-agnostic and works for both HTTP requests and WebSocket upgrades (HMR), so any framework with dev-origin checks benefits automatically.
* increase timeout
portless already works as a local dev dependency (state lives in
~/.portless, not relative to the install path, and there are no
postinstall hooks), but the docs said "don't do this" and the CLI
blocked npx/dlx even for locally-installed packages.
- Add isLocallyInstalled() helper that walks up from cwd looking for
node_modules/portless; the npx/dlx block now only fires for one-off
downloads, not project dependencies
- Update install sections in README, docs site, CLI --help, and agent
skill to show both global and project dev dependency options
- Note the pre-1.0 state-format caveat for per-project installs
Closes#135
* feat: make strict subdomain routing the default, add --wildcard flag
## Summary
Changes the default behavior from wildcard subdomain fallback to strict subdomain routing. This prevents unregistered subdomain prefixes from falling back to the base service, which was confusing in multi-worktree setups.
## Changes
- **Default behavior**: Unregistered subdomains now return 404 instead of falling back to parent routes
- **New flag**: `--wildcard` flag (and `PORTLESS_WILDCARD` env var) to restore the old fallback behavior
- **API changes**: Updated `ProxyOptions` type to use `strict?: boolean` (defaults to true)
- **CLI updates**: Added wildcard flag parsing and help text
- **Tests**: Updated existing tests to explicitly opt into wildcard mode where needed
## Implementation Details
- The `findRoute()` function now requires exact hostname matches by default
- Wildcard fallback is only enabled when `strict: false` is explicitly set
- This change makes git worktree prefixes work as expected - visiting an unregistered worktree URL returns 404 instead of serving the main worktree content
- The change is justified because worktree support is a first-class feature while subdomain fallback was undocumented implicit behavior
Fixes#154
* docs: update subdomain sections to reflect strict-by-default behavior
---------
Co-authored-by: ctate <366502+ctate@users.noreply.github.com>
The documentation lists only four frameworks that need --port/--host
injection (Vite, Astro, React Router, Angular), but the code in
FRAMEWORKS_NEEDING_PORT (cli-utils.ts) and the --help output both
include six: Expo and React Native were dropped during the README
rewrite in #93.
* feat: add Windows support
- Add win32 to os field in package.json
- Use os.tmpdir() for cross-platform SYSTEM_STATE_DIR
- Add parsePidFromNetstat for exact port matching on Windows
- Windows branch in findPidOnPort using netstat -ano
- Windows-aware spawnCommand (shell: true instead of /bin/sh)
- resolveStateDir always uses user dir on Windows (no privileged ports)
- Guard all needsSudo checks with !isWindows
- Guard process.getuid() checks for Unix only
- Platform-aware error messages (netstat/taskkill/Administrator vs lsof/kill/sudo)
- windowsHide: true on daemon spawn
- Windows certificate trust via certutil (isCATrusted + trustCA)
- fixOwnership no-op on Windows
- Windows CI job in GitHub Actions (windows-latest, Node 20/22)
- parsePidFromNetstat test suite (8 cases)
* fix: resolve Windows CI test failures
- auto.test.ts: replace process.env.TMPDIR || "/tmp" with os.tmpdir()
- certs.test.ts: skip chmod permission assertion on Windows
- cli-utils.test.ts: skip privileged port resolveStateDir test on Windows
* fix: match both path separators in worktree detection regex
The /worktrees/ regex used forward slashes only, which fails on
Windows where path.join produces backslashes in the gitdir path.
---------
Co-authored-by: Ben Sabic <bensabic@users.noreply.github.com>
Document automatic worktree detection in portless run -- branch name
is prepended as a subdomain prefix so each worktree gets a unique URL
with no config changes. Added to README, SKILL.md, docs site getting
started page, and changelog.
Register routes for services not spawned by portless (e.g. Docker
containers with published ports). Uses pid 0 as a sentinel so
aliases persist across stale-route cleanup.
Closes#61
Allow specifying a fixed port for the app instead of automatic
assignment. Useful when integrating with tools that provide their
own port (e.g. Conductor) while still using portless hostname routing.
Closes#11
Child processes now receive PORTLESS_URL containing the public .localhost
URL (e.g. http://myapp.localhost:1355) so apps can self-reference their
own URL without hardcoding it.
README and --help text are updated to distinguish variables injected into
child processes (PORT, HOST, PORTLESS_URL) from configuration variables
read by portless itself (PORTLESS_PORT, PORTLESS_HTTPS, PORTLESS_STATE_DIR).
When a backend proxies requests back through portless without
rewriting the Host header (e.g. Vite proxy without changeOrigin),
an infinite loop occurs. Each hop appends to X-Forwarded-For until
Node.js rejects the request with 431.
Now portless checks the hop count in X-Forwarded-For and responds
with 508 Loop Detected after 10 hops, with a message pointing to
the fix (changeOrigin: true).
Also adds documentation about this pitfall in README.md and SKILL.md.
Closes#47
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Chris Tate