portless

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
pnpm dev        # -> works without portless, plain "next dev"

Use an optional portless.json to override defaults (name, script, port):

{ "name": "myapp" }

portless        # -> runs "dev" script, https://myapp.localhost

One portless.json at the repo root. 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: start all packages with a "dev" script
cd apps/web && portless   # start just one package
portless --script start   # run "start" instead of "dev"

The apps map is optional and only provides name overrides. Unlisted packages auto-discover with inferred names.

Without an apps map, hostnames follow <package>.<project>.localhost. The project name comes from the most common npm scope (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 uses the bare <project>.localhost.

For turborepo projects, use portless as the dev script with the real command in a separate script:

{
  "scripts": { "dev": "portless", "dev:app": "next dev" },
  "portless": { "name": "myapp", "script": "dev:app" }
}

pnpm dev runs turbo, which runs portless in each package. Portless detects the package manager and runs pnpm run dev:app through the proxy.

When portless runs from a workspace root, it uses the existing Turbo integration to preserve task ordering when either turbo.json or turbo.jsonc is readable. Set "turbo": false in the root portless configuration to use direct spawning instead.

You can still use portless directly in scripts:

{
  "scripts": {
    "dev": "portless run next dev"
  }
}

The proxy auto-starts when you run an app. Or start it explicitly: portless proxy start.

portless myapp next dev          # https://myapp.localhost
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). Start the proxy with --wildcard to allow any subdomain of a registered route to fall back to that app (e.g. tenant1.myapp.localhost routes to the myapp app). Exact matches always take priority over wildcards.

portless run automatically detects git worktrees. In a linked worktree, the branch name is prepended as a subdomain prefix so each worktree gets a unique URL:

# 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

No config changes needed. Put portless run in package.json once and it works in all worktrees.

Set PORTLESS=0 to run the command directly without the proxy:

PORTLESS=0 pnpm dev   # Bypasses proxy, uses default port

When a proxied command is stopped with Ctrl+C, portless waits for its process tree to exit. A second Ctrl+C forwards another interrupt, and remaining descendants are terminated after a short grace period.

Portless stores its state (routes, PID file, port file) in ~/.portless. When the proxy runs under sudo, this remains the invoking user's home directory so unprivileged apps and the proxy share route registrations. Override with the PORTLESS_STATE_DIR environment variable.

HTTPS with HTTP/2 is enabled by default (faster page loads for dev servers with many files). WebSockets work over both HTTP/1.1 (Upgrade) and HTTP/2 (RFC 8441 extended CONNECT), so dev server HMR works through the proxy. First run generates a local CA and adds it to the system trust store. After that, no prompts and no browser warnings.

portless proxy start --cert ./c.pem --key ./k.pem  # Use custom certs
portless proxy start --no-tls                       # Disable HTTPS (plain HTTP)
portless trust                                      # Add CA to trust store later

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.

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 advertises <name>.local hostnames over mDNS so devices on the same Wi-Fi can reach your apps. Portless auto-detects your LAN IP and follows network changes automatically, but you can pin a specific address with --ip <address> or the PORTLESS_LAN_IP environment variable. Set PORTLESS_LAN=1 to default to LAN mode every time the proxy starts.

Portless remembers LAN mode via proxy.lan, so if you stop a LAN proxy and start 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 helpers that portless launches: macOS includes dns-sd, while Linux uses avahi-publish-address from avahi-utils (install via sudo apt install avahi-utils or your distro’s tooling).

• Next.js: add your .local hostnames to allowedDevOrigins:

  Copy

  // 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 localhost outside LAN mode, but in LAN mode portless leaves Metro on its default LAN host behavior instead of forcing --host or HOST.

Share dev servers with teammates on your Tailscale network using --tailscale, or expose to the public internet with --funnel:

portless myapp --tailscale next dev
# -> https://myapp.localhost           (local)
# -> https://devbox.yourteam.ts.net    (tailnet)

portless myapp --funnel next dev
# -> https://myapp.localhost           (local)
# -> https://devbox.yourteam.ts.net    (public internet)

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.

Each --tailscale app is root-mounted on its own Tailscale HTTPS port (443, then 8443, 8444, etc.) so no framework basePath configuration is needed. Set PORTLESS_TAILSCALE=1 to share every app by default. portless list shows both local and tailnet URLs. Tailscale serve registrations are cleaned up when the app exits. Requires tailscale CLI installed and connected, with Tailscale HTTPS certificates enabled.

Expose a dev server to the public internet with ngrok using --ngrok:

portless myapp --ngrok next dev
# -> https://myapp.localhost           (local)
# -> https://abc123.ngrok.app          (public internet)

Set PORTLESS_NGROK=1 to enable ngrok by default when portless runs an app. portless list shows both local and ngrok URLs. The ngrok tunnel is cleaned up when the app exits. Requires the ngrok CLI to be installed and authenticated with ngrok config add-authtoken <token>.

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:

{ "portless": "myapp" }

An object supports all per-app fields (name, script, appPort, proxy):

{ "portless": { "name": "myapp", "script": "dev:app" } }

Precedence (closest wins): CLI flags > package.json "portless" key > portless.json app entry > defaults.

Use portless doctor first when local routing or HTTPS behavior looks wrong. It is read-only and checks Node.js, state directory permissions, proxy liveness, route entries, hostname resolution, local CA trust, and LAN mode prerequisites.

The proxy auto-starts when you run an app with portless <name> <cmd>. If it doesn't start (e.g. port conflict), start it manually:

portless proxy start

Another process is bound to the proxy port. Either stop it first, or use a different port:

portless proxy start -p 8080

Portless auto-injects the right --port flag and, when needed, a matching --host flag for frameworks that ignore the PORT env var: Vite, VitePlus (vp), Astro, React Router, Angular, Expo, and React Native. SvelteKit uses Vite internally and is handled automatically. Injection reaches through a package script whose command starts with the framework or a known runner, and only for the framework's server commands (dev, serve, preview, start, or a bare vite) — vite build, vite optimize, vp test and other non-serving commands reject the flags, so they are left untouched, as is any invocation portless cannot classify (vp --mode dev build). It is also skipped for a compound command (&&, |, ;), a trailing # comment, its own -- option terminator, an env prefix (NODE_ENV=production vite), delegation to another script, and runner flags before the script name (bun run --bun dev) — each of those keeps its own port and the app returns 502, so set the port in the script yourself.

For other frameworks that don't read PORT, pass the port manually:

• Webpack Dev Server: use --port $PORT
• Custom servers: read process.env.PORT and listen on it

The default ports (80 for HTTP, 443 for HTTPS) require sudo on macOS and Linux. Portless auto-elevates with sudo when needed. If sudo is unavailable, it falls back to port 1355 (no sudo needed). On Windows, no elevation is required.

portless proxy start --https           # Auto-elevates with sudo for port 443
portless proxy start -p 1355 --https   # No sudo needed (URLs include :1355)
portless proxy stop                    # Stop (use sudo if started with sudo)

Safari relies on the system DNS resolver for .localhost subdomains, which may not resolve them on all macOS configurations. Chrome, Firefox, and Edge have built-in handling.

Fix:

portless hosts sync    # Adds current routes to /etc/hosts
portless hosts clean   # Remove entries later

Auto-syncs /etc/hosts for route hostnames by default. 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.

The local CA may not be trusted yet. Run:

portless trust

This adds the portless local CA to your system trust store. After that, restart the browser.

portless clean

Stops the proxy if needed, removes the portless CA from the trust store (when portless added it), deletes known files under state directories, and removes the portless /etc/hosts block. May require sudo on macOS/Linux. If trust-store removal fails, portless retains its CA certificate and key so a later portless clean can safely retry.

If your dev server proxies requests to another portless app (e.g. Vite proxying /api to api.myapp.localhost), the proxy must rewrite the Host header. Without this, portless routes the request back to the original app, creating an infinite loop.

Fix: set changeOrigin: true in the proxy config (Vite, webpack-dev-server, etc.):

// vite.config.ts
proxy: {
  "/api": {
    target: "https://api.myapp.localhost",
    changeOrigin: true,
    ws: 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.

If --tailscale or --funnel fails:

tailscale status     # Check if connected
tailscale up         # Connect to your tailnet

Requires the Tailscale CLI to be installed (https://tailscale.com/download) and on PATH.

If --ngrok fails:

ngrok version                         # Check if installed
ngrok config add-authtoken <token>    # Configure authentication

Requires the ngrok CLI to be installed (https://ngrok.com/download) and on PATH.

• Node.js 24+
• macOS, Linux, or Windows
• openssl (for --https cert generation; ships with macOS and most Linux distributions; on Windows, install via winget install -e --id ShiningLight.OpenSSL.Dev or use the copy bundled with Git for Windows)
• tailscale CLI (optional, for --tailscale and --funnel)
• ngrok CLI (optional, for --ngrok)