Railly Hugo
1ad573bb95
* fix: report automatic hosts-sync failures on the CLI, not only in proxy.log The automatic sync ignored the result of `syncHostsFile`, so an unprivileged run registered a route, skipped the hosts block and said nothing. On resolvers that do not handle multi-label `.localhost` the app then fails with `ENOTFOUND` and nothing points at the skipped sync. The sync runs in the detached daemon, whose stdio is redirected to `proxy.log`, so the outcome has to cross a process boundary to reach the terminal that caused it. It crosses on a request: the CLI asks the proxy over loopback after registering, and the daemon reloads routes, syncs with its own privileges and setting, and answers on the same connection. An answer carried by its request cannot be stale, cannot belong to another caller, and cannot be left behind by a previous daemon, so it needs no timestamp, owner or schema version, and no state file. Two guards. A loopback request Host selects the route, so an app that serves the same path keeps serving it. A loopback peer address is then required, because a Host header is attacker-supplied and LAN mode binds every interface. The request carries no data: hostnames come from the daemon's route table, so nothing an attacker supplies reaches the hosts file. A daemon older than this route answers 404 in milliseconds, and the CLI then reads the hosts file to see whether the hostnames resolve. That fallback is also what happens when an answer does not arrive in time, where claiming failure would be a guess. `syncHostsFile` now reports whether the hosts file resolves the given hostnames rather than whether a write threw. The two differ when the block is already correct, and it returns early in that case, so a route reload that changes nothing no longer rewrites the file. Measured against an unwritable hosts file: warning delivered in 0.07 to 0.09s, including against a daemon built from main and against a CLI whose own PORTLESS_SYNC_HOSTS is 0. As root in a container, where the write succeeds: registration completes in 0.04 to 0.06s, silent, with the hostname resolving. * fix: skip a hosts sync on exactness, report on coverage Two questions were collapsed into one. Whether to skip the write is exactness, because the write rebuilds the block to exactly the route set, so a coverage test called a superset correct and the skip left a removed route's hostname resolving forever. What to report is coverage, because the caller asks whether its own hostname resolves, and answering with exactness makes an unprivileged daemon that cannot delete someone else's stale entry report failure to every registration that actually works. `hosts sync` with no routes now clears the block instead of returning early. Zero routes is a desired state, and bailing there meant a block left by routes that are gone survived the command the warning tells people to run. An older daemon's 404 no longer produces a warning. Success, a failed write and opt-out all look identical from a 404, and that daemon syncs later on its own watcher, so reading the hosts file on receipt reported a failure it was about to not have. Waiting instead only moves the guess later, since an absence at any deadline still cannot separate a failed write from a user who disabled syncing. An unreachable proxy is reported, but as an unconfirmed sync rather than a write that was never observed to fail. The response is also checked for the X-Portless header the liveness probe already checks, since proxy.port can be stale or reused and an unrelated local server answering "disabled" restored the silence this fixes. Driven as root in a container: a removed route's entry disappears, `hosts sync` clears an orphaned block, and a redundant sync still leaves the file untouched. Unprivileged, every path stays between 0.07 and 0.34s. * fix: warn when a route hostname will not resolve, not when a write failed Issue #364 asks for a warning at registration time, and the question behind it is whether the app is about to fail with ENOTFOUND. That is not the same question as whether /etc/hosts was written. RFC 6761 makes .localhost resolution a SHOULD for resolvers, and on current macOS and glibc `app.localhost` resolves with no hosts entry, so a skipped write there changes nothing a user can see. A custom TLD like `app.test` resolves on neither, so there the skipped write is the whole problem. Reporting the write cannot tell those apart. After registering a route the CLI asks the proxy over loopback to sync now, then reads the resolver once. The request is a trigger: it removes the wait for the daemon's file watcher, and its answer is not trusted for anything, so it carries no body. Whether the responder is the daemon we meant, whether it is new enough to understand the request, and what it claims happened are all irrelevant, because the resolver is authoritative and local. `checkHostResolution` already existed and was already used by `portless doctor`. Order matters: querying before the write can cache a negative that is about to become false, and macOS caches negatives, so an early probe could break the resolution it checks. `syncHostsFile` reports whether the block matches exactly, which is the writer's own question, and restores the sudo escalation in `hosts sync` that a coverage return had silently disabled. The weak question now belongs to the caller asking it. A daemon started with PORTLESS_SYNC_HOSTS=0 no longer gets a special case: if the hostname resolves the user hears nothing, and if it does not, their app is broken and they are told. Measured unprivileged: .localhost silent in 0.076s, .test warned in 0.101s. As root in a container, where the write succeeds: silent in 0.053s with the hostname resolving, a removed route's entry gone, a redundant sync leaving the file untouched, and `hosts sync` failing honestly instead of reporting success. * fix(cli): give an untriggerable daemon its chance before reporting absence The trigger discarded the one bit worth keeping: whether a daemon acknowledged doing the work. Without it, a daemon too old to have the internal route answered 404, the CLI read the resolver immediately, and warned about an absence that daemon was one debounce away from fixing. Driven against a build of main with a custom TLD: the warning printed, and the hostname resolved two seconds later. The trigger now reports acknowledgement. A daemon that acknowledged has already attempted the write, so one read of the resolver settles it. Nothing acknowledged means nobody acted on our behalf, and anything that still happens happens on a watcher's schedule, so the resolver is polled to a bound that clears it. Only that path pays the bound. Measured unprivileged against a current daemon: .localhost silent in 0.078s, a failing custom TLD warned in 0.092s. * fix(cli): keep the watcher's before-image, and stop waiting on a producer that is absent Three defects, all in the reporting path added by this branch. The hosts-sync handler read the current route set into `cachedRoutes`, which is the route watcher's before-image. `reloadRoutes` diffs a fresh load against it to decide which mDNS records to publish, so overwriting it made the next diff compare the new route set with itself and a route registered this way never got a `.local` publisher at all. It reads into a local now. The trigger reported only whether a daemon acknowledged, so a refused connection and an unacknowledged answer were treated alike and both paid the poll. Waiting when nothing is listening spends a ceiling to learn what the refused connection already said, and it timed out two tests locally, two on Linux CI and seven on Windows. The trigger now distinguishes an absent listener from a mute one, and only a mute one is waited on. Measured: a custom TLD with no daemon went from 3.61s to 0.07s and still warns. A `.local` hostname is served by mDNS and correctly resolves to the machine's LAN address, so asking whether it resolves to loopback answered no for a hostname that works. Those names are no longer this warning's business. * refactor: drop the internal endpoint, wait on the hosts file instead The endpoint, its two guards, the acknowledgement bit and the version-skew branch existed only to make the failure path fast. Reading the hosts file to know when the daemon has written costs 3.6s on that path and deletes all of it, leaving proxy.ts and types.ts identical to main. Waiting by reading the file rather than re-querying the resolver also removes the cached-negative hazard that made ordering load-bearing. Comments rewritten short and stale ones corrected: four still described the request channel that no longer exists. * fix(cli): make hosts sync state explicit * fix(portless): authenticate hosts sync requests * refactor(portless): simplify hosts sync security tests
portless
Replace port numbers with stable, named .localhost URLs for local development. For humans and agents.
- "dev": "next dev" # http://localhost:3000
+ "dev": "portless run next dev" # https://myapp.localhost
Install
Global (recommended):
npm install -g portless
Or as a project dev dependency:
npm install -D portless
portless is pre-1.0. When installed per-project, different contributors may run different versions. The state directory format may change between releases, which can require re-running
portless trust.
Run your app
portless myapp next dev
# -> https://myapp.localhost
HTTPS with HTTP/2 is enabled by default. On first run, portless generates a local CA, trusts it, and binds port 443 (auto-elevates with sudo on macOS/Linux). Use --no-tls for plain HTTP.
The proxy auto-starts when you run an app. A random port (4000-4999) is assigned via the PORT environment variable. Most frameworks (Next.js, Express, Nuxt, etc.) respect this automatically. For frameworks that ignore PORT (Vite, VitePlus, Astro, React Router, Angular, Expo, React Native), portless auto-injects the right --port flag and, when needed, a matching --host flag. Injection reaches through a package script whose command starts with the framework or a known runner ("dev": "vite", "dev": "bunx vite"). Only the framework's server commands get the flags (dev, serve, preview, start, a bare vite, or vite [root]); a command that does not serve, such as vite build, vite optimize, vp test or astro check, rejects them and is left alone. Expo connection modes (--localhost, --lan, --tunnel) are preserved while the assigned port is still injected. A script portless cannot classify is left alone too: a flag before the subcommand on a CLI whose flag grammar it does not track (vp --mode dev build). Portless also leaves a script alone when appending flags to it would not work: a compound command (&&, |, ;), a trailing # comment, its own -- option terminator, an env prefix (NODE_ENV=production vite), delegation to another script ("dev": "npm run dev:vite"), or runner flags before the script name (bun run --bun dev). Those keep their own port, so set it in the script yourself.
When auto-starting, portless reuses the configuration (port, TLS, TLDs) from the most recent proxy run, so a restart or reboot does not silently revert to defaults. Explicit env vars (PORTLESS_PORT, PORTLESS_HTTPS, etc.) always take priority.
Portless stores per-user state in ~/.portless. When the proxy runs under sudo, it resolves this path from the invoking user's home so the proxy and unprivileged app processes share the same route registrations.
In non-interactive environments (no TTY, or CI=1), portless exits with a descriptive error instead of prompting, so task runners like turborepo and CI scripts fail early with a clear message.
Configuration
Bare portless works out of the box. It runs the "dev" script from package.json through the proxy, inferring the app name from the package name, git root, or directory:
portless # -> runs "dev" script, https://<project>.localhost
Use an optional portless.json to override defaults:
{ "name": "myapp" }
portless # -> runs "dev" script, https://myapp.localhost
The script defaults to "dev". The name is inferred from package.json if not set in config.
Monorepo
One portless.json at the repo root covers all workspace packages. Portless discovers packages from pnpm-workspace.yaml, or the "workspaces" field in package.json (npm, yarn, bun):
{
"apps": {
"apps/web": { "name": "myapp" },
"apps/api": { "name": "api.myapp" }
}
}
portless # from repo root: starts all workspace packages with a "dev" script
cd apps/web && portless # start just one package
The apps map is optional and only needed for name overrides. Packages not listed still auto-discover with names inferred from their package.json.
Without an apps map, hostnames follow the <package>.<project>.localhost convention. The project name comes from the most common npm scope across workspace packages (e.g. @myorg/web and @myorg/api produce myorg), falling back to the workspace root directory name. If a package's short name matches the project name, it gets the bare <project>.localhost without duplication.
Config fields
| Field | Type | Default | Description |
|---|---|---|---|
name |
string | inferred | Base app name. Worktree prefix still applies. |
script |
string | "dev" |
Name of a package.json script to run. |
appPort |
number | auto | Fixed port for the child process. |
proxy |
boolean | auto | Whether to route through the proxy. Auto-detected. |
apps |
object | Overrides for workspace packages, keyed by relative path. | |
turbo |
boolean | true |
Set false to use direct spawning instead of turborepo. |
package.json "portless" key
Instead of a separate portless.json, you can add a "portless" key to your package.json. A string value is shorthand for setting the name:
{
"name": "@myorg/web",
"portless": "myapp"
}
An object supports all per-app fields (name, script, appPort, proxy):
{
"name": "@myorg/web",
"portless": { "name": "myapp", "script": "dev:app" }
}
The package.json "portless" key takes precedence over portless.json app entries but is overridden by CLI flags.
--script flag
Override the default script for a single invocation:
portless --script start # run "start" instead of "dev"
portless --script test # run "test" instead of "dev"
Turborepo
To use portless with turborepo, put portless as the dev script and the real command in a separate script:
{
"scripts": {
"dev": "portless",
"dev:app": "next dev"
},
"portless": { "name": "myapp", "script": "dev:app" }
}
Turbo runs each package's dev script, which invokes portless. Portless reads the config, detects the package manager, and runs pnpm run dev:app (or yarn/bun/npm) through the proxy. No changes to turbo.json are needed.
pnpm dev at the root works through turbo as usual. People without portless can run pnpm run dev:app directly.
Use in package.json
You can still use portless in package.json scripts:
{
"scripts": {
"dev": "portless run next dev"
}
}
With a portless.json, you can simplify to:
{
"scripts": {
"dev": "next dev"
}
}
Then run portless or portless run to go through the proxy.
When you press Ctrl+C, portless forwards the interrupt and waits for the command's process tree to exit. Press Ctrl+C again to forward another interrupt. Any remaining descendants are terminated after a short grace period.
Subdomains
Organize services with subdomains:
portless api.myapp pnpm start
# -> https://api.myapp.localhost
portless docs.myapp next dev
# -> https://docs.myapp.localhost
By default, only explicitly registered subdomains are routed (strict mode). Use --wildcard when starting the proxy to allow any subdomain of a registered route to fall back to that app (e.g. tenant1.myapp.localhost routes to the myapp app without extra registration).
Git Worktrees
portless run automatically detects git worktrees. In a linked worktree, the branch name is prepended as a subdomain so each worktree gets its own URL without any config changes:
# Main worktree (no prefix)
portless run next dev # -> https://myapp.localhost
# Linked worktree on branch "fix-ui"
portless run next dev # -> https://fix-ui.myapp.localhost
Use --name to override the inferred base name while keeping the worktree prefix:
portless run --name myapp next dev # -> https://fix-ui.myapp.localhost
Put portless run in your package.json once and it works everywhere. The main checkout uses the plain name, each worktree gets a unique subdomain. No collisions, no --force.
Custom TLD
By default, portless uses .localhost which auto-resolves to 127.0.0.1 in most browsers. If you prefer a different TLD (e.g. .test), use --tld:
portless proxy start --tld test
portless myapp next dev
# -> https://myapp.test
The proxy auto-syncs /etc/hosts for route hostnames (including .test), so those domains resolve on your machine.
Repeat --tld to serve the same app names under multiple TLDs from one proxy:
portless proxy start --tld localhost --tld test
portless myapp next dev
# -> https://myapp.localhost
# -> https://myapp.test
When multiple TLDs are configured, PORTLESS_URL uses the first TLD. PORTLESS_TLD also accepts a comma separated list, e.g. PORTLESS_TLD=localhost,test.
Recommended: .test (IANA-reserved, no collision risk). Avoid .local (conflicts with mDNS/Bonjour) and .dev (Google-owned, forces HTTPS via HSTS).
Multi-segment TLDs
The --tld value accepts a lowercase DNS name (one or more dot-separated labels, no trailing dot), so a domain you own can be used as the "TLD". This gives local URLs the same structure as production, which keeps OAuth redirect URIs, cross-subdomain cookies, and host-based routing working the same way in both environments:
portless proxy start --tld dev.example.com
portless myapp next dev
# -> https://myapp.dev.example.com
Each label must follow DNS rules: lowercase letters, digits, and interior hyphens, with at most 63 characters per label and 253 characters total. The full hostname (app.TLD) is also subject to the 253-character DNS limit.
The proxy auto-syncs /etc/hosts for registered hostnames, so myapp.dev.example.com resolves to 127.0.0.1 on your machine. This is a loopback-only setup: outside LAN mode the proxy binds only to 127.0.0.1 and ::1 (see below), so a custom TLD is reachable only from the machine running the proxy. Reaching the proxy from other devices requires LAN mode (--lan), but LAN mode serves apps under the .local TLD and ignores a custom --tld, so the two cannot be combined today.
Strict OAuth providers (Google, Apple) reject .localhost and .test redirect URIs but accept a real domain, so https://myapp.dev.example.com/api/auth/callback/google works as a redirect URI.
How it works
flowchart TD
Browser["Browser<br>myapp.localhost"]
Proxy["portless proxy<br>(port 80 or 443)"]
App1[":4123<br>myapp"]
App2[":4567<br>api"]
Browser --> Proxy
Proxy --> App1
Proxy --> App2
- Start the proxy: auto-starts when you run an app, or start explicitly with
portless proxy start - Run apps:
portless <name> <command>assigns a free port and registers with the proxy - Access via URL:
https://<name>.localhostroutes through the proxy to your app
Outside LAN mode, the proxy and its HTTP redirect listener bind only to the IPv4 and IPv6 loopback addresses, 127.0.0.1 and ::1. They do not accept connections through LAN, VPN, or other network interfaces.
HTTP/2 + HTTPS
HTTPS with HTTP/2 is enabled by default. Browsers limit HTTP/1.1 to 6 connections per host, which bottlenecks dev servers that serve many unbundled files (Vite, Nuxt, etc.). HTTP/2 multiplexes all requests over a single connection.
WebSockets work over both protocol versions, so dev server HMR (Next.js, Vite, etc.) works through the proxy: HTTP/1.1 Upgrade requests are forwarded as-is, and WebSockets opened over an HTTP/2 connection use extended CONNECT (RFC 8441).
On first run, portless generates a local CA and adds it to your system trust store. No browser warnings. No manual setup.
# Use your own certs (e.g., from mkcert)
portless proxy start --cert ./cert.pem --key ./key.pem
# Disable HTTPS (plain HTTP on port 80)
portless proxy start --no-tls
# If you skipped the trust prompt on first run, trust the CA later
portless trust
On Linux, portless trust supports Debian/Ubuntu, Arch, Fedora/RHEL/CentOS, and openSUSE (via update-ca-certificates or update-ca-trust). On Windows, it uses certutil to add the CA to the system trust store. On WSL, it updates both the Linux trust store and the Windows current-user Root store so Windows browsers trust portless HTTPS certificates.
Start at OS startup
Install the proxy as an OS startup service so clean HTTPS URLs are available after reboot without starting the proxy from a terminal:
portless service install
portless service install --lan
portless service install --wildcard
PORTLESS_STATE_DIR=~/.portless-lan PORTLESS_LAN=1 portless service install
portless service status
portless service uninstall
The service uses portless defaults unless install options or PORTLESS_* environment variables are provided: HTTPS on port 443 with .localhost names. service install accepts the proxy options you would use with proxy start, including --port, --no-tls, --lan, --ip, --tld, --wildcard, --cert, and --key. Use --state-dir <path> or PORTLESS_STATE_DIR=<path> to choose where service state and logs are written.
The chosen service configuration is written into launchd, systemd, or Task Scheduler and reused after reboot. portless service status reports the installed port, HTTPS mode, TLDs, LAN mode, wildcard mode, and state directory. macOS and Linux install a root-owned service so port 443 can bind at boot. Windows installs a Task Scheduler startup task that runs as SYSTEM. Installation and removal may require administrator privileges. portless clean automatically removes the service.
LAN mode
portless proxy start --lan
portless proxy start --lan --https
portless proxy start --lan --ip 192.168.1.42
--lan explicitly binds the proxy to the IPv4 and IPv6 unspecified addresses, 0.0.0.0 and ::, and switches to mDNS discovery. This makes services available as <name>.local to devices on the same network. Portless auto-detects your LAN IP and follows Wi-Fi/IP changes automatically, but you can pin another address with --ip <address> or by exporting PORTLESS_LAN_IP. Set PORTLESS_LAN=1 in your shell (0/1 boolean) to make LAN mode the default whenever the proxy starts.
Portless remembers LAN mode via proxy.lan, so if you stop a LAN proxy and start it again, it stays in LAN mode. All proxy settings (port, TLS, TLDs, LAN) are persisted and reused on auto-start unless overridden by explicit flags or env vars. Use PORTLESS_LAN=0 for one start to switch back to .localhost mode. If a proxy is already running with different explicit LAN/TLS/TLD settings, portless warns and asks you to stop it first.
LAN mode depends on the system mDNS tools that portless already spawns: macOS ships with dns-sd, while Linux uses avahi-publish-address from avahi-utils (install via sudo apt install avahi-utils or your distro’s equivalent). If the command is missing or your network isn’t reachable, portless proxy start --lan prints the relevant error and exits.
Framework notes
-
Next.js: add your
.localhostnames toallowedDevOrigins:// next.config.js module.exports = { allowedDevOrigins: ["myapp.local", "*.myapp.local"], }; -
Expo / React Native: portless always injects
--port. React Native also gets--host 127.0.0.1. Expo gets--host localhostoutside LAN mode, but in LAN mode portless leaves Metro on its default LAN host behavior instead of forcing--hostorHOST.
Tailscale sharing
Share your dev server with teammates on your Tailscale network:
portless myapp --tailscale next dev
# -> https://myapp.localhost (local)
# -> https://devbox.yourteam.ts.net (tailnet)
Each --tailscale app is root-mounted on its own Tailscale HTTPS port, so no framework basePath configuration is needed. The first app gets port 443, subsequent apps get 8443, 8444, etc.
portless myapp --tailscale next dev # -> https://devbox.ts.net
portless api --tailscale pnpm start # -> https://devbox.ts.net:8443
Use --funnel to expose your dev server to the public internet via Tailscale Funnel:
portless myapp --funnel next dev
# -> https://devbox.yourteam.ts.net (public)
Tailscale HTTPS certificates must be enabled before --tailscale or --funnel can register HTTPS URLs. Funnel must also be enabled for the tailnet and node before --funnel can register the public URL. If either setting is missing, portless exits before starting the child process.
Set PORTLESS_TAILSCALE=1 in your shell profile or .env to share every app by default. portless list shows both local and tailnet URLs. Tailscale serve registrations are cleaned up automatically when the app exits.
Requires the Tailscale CLI to be installed and connected (tailscale up), with Tailscale HTTPS certificates enabled.
ngrok sharing
Expose your dev server to the public internet with ngrok:
portless myapp --ngrok next dev
# -> https://myapp.localhost (local)
# -> https://abc123.ngrok.app (public)
Set PORTLESS_NGROK=1 in your shell profile or .env to enable ngrok by default when portless runs an app. portless list shows both local and ngrok URLs. The ngrok tunnel is cleaned up automatically when the app exits.
Requires the ngrok CLI to be installed and authenticated. If ngrok reports an authentication error, run ngrok config add-authtoken <token> and try again.
Commands
portless # Run dev script through proxy
portless # From monorepo root: run all workspace packages
portless run [--name <name>] [cmd] [args...] # Infer name, run through proxy
portless <name> <cmd> [args...] # Run app at https://<name>.localhost
portless alias <name> <port> # Register a static route (e.g. for Docker)
portless alias <name> <port> --force # Overwrite an existing route
portless alias --remove <name> # Remove a static route
portless list # Show active routes
portless doctor # Check proxy, routes, DNS, and CA trust
portless trust # Add local CA to system trust store
portless clean # Remove state, CA trust entry, and hosts block
portless prune # Kill orphaned dev servers from crashed sessions
portless hosts sync # Add routes to /etc/hosts (fixes Safari)
portless hosts clean # Remove portless entries from /etc/hosts
# Disable portless (run command directly)
PORTLESS=0 pnpm dev # Bypasses proxy, uses default port
# Proxy control
portless proxy start # Start the HTTPS proxy (port 443, daemon)
portless proxy start --no-tls # Start without HTTPS (port 80)
portless proxy start --lan # Start in LAN mode (mDNS .local for devices)
portless proxy start -p 1355 # Start on a custom port (no sudo)
portless proxy start --foreground # Start in foreground (for debugging)
portless proxy start --wildcard # Allow unregistered subdomains to fall back to parent
portless proxy stop # Stop the proxy
# OS startup service
portless service install # Start HTTPS proxy when the OS starts
portless service install --lan # Start service in LAN mode
portless service install --wildcard # Persist wildcard routing in the service
portless service status # Show service and proxy status
portless service uninstall # Remove the startup service
Options
-p, --port <number> Port for the proxy (default: 443, or 80 with --no-tls)
--no-tls Disable HTTPS (use plain HTTP on port 80)
--https Enable HTTPS (default, accepted for compatibility)
--lan Enable LAN mode (mDNS .local for real devices)
--ip <address> Pin a specific LAN IP (disables auto-follow; use with --lan)
--cert <path> Use a custom TLS certificate
--key <path> Use a custom TLS private key
--foreground Run proxy in foreground instead of daemon
--tld <tld> Use a custom TLD instead of .localhost; repeat for more
--wildcard Allow unregistered subdomains to fall back to parent route
--state-dir <path> Use a custom state directory with service install
--script <name> Run a specific package.json script (default: dev)
--app-port <number> Use a fixed port for the app (skip auto-assignment)
--tailscale Share the app on your Tailscale network (tailnet)
--funnel Share the app publicly via Tailscale Funnel
--ngrok Share the app publicly via ngrok
--force Kill the existing process and take over its route
--name <name> Use <name> as the app name
Environment variables
# Configuration
PORTLESS_PORT=<number> Override the default proxy port
PORTLESS_APP_PORT=<number> Use a fixed port for the app (same as --app-port)
PORTLESS_HTTPS=0 Disable HTTPS (same as --no-tls)
PORTLESS_LAN=1 Enable LAN mode when set to 1 (auto-detects LAN IP)
PORTLESS_LAN_IP=<address> Pin a specific LAN IP for LAN mode
PORTLESS_TLD=<tld>[,<tld>] Use one or more TLDs (e.g. localhost,test)
PORTLESS_WILDCARD=1 Allow unregistered subdomains to fall back to parent route
PORTLESS_SYNC_HOSTS=0 Disable auto-sync of /etc/hosts (on by default)
PORTLESS_TAILSCALE=1 Share apps on your Tailscale network (same as --tailscale)
PORTLESS_FUNNEL=1 Share apps publicly via Tailscale Funnel (same as --funnel)
PORTLESS_NGROK=1 Share apps publicly via ngrok (same as --ngrok)
PORTLESS_STATE_DIR=<path> Override the state directory
# Injected into child processes
PORT Ephemeral port the child should listen on
HOST Usually 127.0.0.1 (omitted for Expo in LAN mode)
PORTLESS_URL Primary public URL (e.g. https://myapp.localhost)
PORTLESS_TAILSCALE_URL Tailscale URL of the app (when --tailscale is active)
PORTLESS_NGROK_URL ngrok URL of the app (when --ngrok is active)
NODE_EXTRA_CA_CERTS Path to the portless CA (when HTTPS is active)
Reserved names:
run,get,alias,hosts,list,doctor,trust,clean,prune,proxy, andserviceare subcommands and cannot be used as app names directly. Useportless run <cmd>to infer the name from your project, orportless --name <name> <cmd>to force any name including reserved ones.
Uninstall / reset
To remove portless data from your machine (proxy state under ~/.portless and the system state directory, the local CA from the OS trust store when portless installed it, and the portless block in /etc/hosts):
portless clean
macOS/Linux may prompt for sudo. Custom certificate paths passed with --cert and --key are not deleted. If trust-store removal fails, portless retains its CA certificate and key so a later portless clean can safely retry.
Safari / DNS
.localhost subdomains auto-resolve to 127.0.0.1 in Chrome, Firefox, and Edge. Safari relies on the system DNS resolver, which may not handle .localhost subdomains on all configurations.
If Safari can't find your .localhost URL:
portless hosts sync # Add current routes to /etc/hosts
portless hosts clean # Clean up later
Auto-syncs /etc/hosts for route hostnames by default (.localhost, custom TLDs, LAN .local). Set PORTLESS_SYNC_HOSTS=0 to disable. If a route hostname will not resolve, the command that registered it warns and points you to portless hosts sync.
Troubleshooting
Run portless doctor to inspect local health without changing state. It checks Node.js, the state directory, proxy liveness, route entries, HTTPS CA trust, hostname resolution, and LAN mode prerequisites, then prints suggested fixes.
Proxying Between Portless Apps
If your frontend dev server (e.g. Vite, webpack) proxies API requests to another portless app, make sure the proxy rewrites the Host header. Without this, portless routes the request back to the frontend in an infinite loop.
Vite (vite.config.ts):
server: {
proxy: {
"/api": {
target: "https://api.myapp.localhost",
changeOrigin: true,
ws: true,
},
},
}
webpack-dev-server (webpack.config.js):
devServer: {
proxy: [{
context: ["/api"],
target: "https://api.myapp.localhost",
changeOrigin: true,
}],
}
Portless automatically sets NODE_EXTRA_CA_CERTS in child processes so Node.js trusts the portless CA. If you run a separate Node.js process outside portless, point it at the CA manually: NODE_EXTRA_CA_CERTS=~/.portless/ca.pem. Alternatively, use --no-tls for plain HTTP.
Portless detects this misconfiguration and responds with 508 Loop Detected along with a message pointing to this fix.
Development
This repo is a pnpm workspace monorepo using Turborepo. The publishable package lives in packages/portless/.
Use Node.js 24+ and pnpm 11 for repository development. The .node-version file pins the Node major for version managers.
pnpm install # Install all dependencies
pnpm build # Build all packages
pnpm test # Run tests
pnpm test:coverage # Run tests with coverage
pnpm lint # Lint all packages
pnpm type-check # Type-check all packages
pnpm format # Format all files with Prettier
Requirements
- Node.js 24+
- macOS, Linux, or Windows
- Tailscale CLI (optional, for
--tailscaleand--funnel) - ngrok CLI (optional, for
--ngrok)