portless-local

Portless - Named .localhost URLs

Replace port numbers with stable, named .localhost URLs for local development. For humans and agents.

Note: The portless CLI enables HTTPS on port 443 by default (https://myapp.localhost). Pass --no-tls to portless proxy start, or set PORTLESS_HTTPS=0, for plain HTTP. Keep HTTPS when the app needs OAuth, secure cookies, or HTTP/2.

Safety and Approval

Read existing proxy configuration before starting an app: auto-start reuses saved settings, including LAN mode. Outside LAN mode the proxy binds only to IPv4/IPv6 loopback; LAN mode binds all interfaces.

Ask for explicit approval before first-run sudo/elevation, CA trust-store changes, /etc/hosts writes, LAN exposure, Tailscale sharing, public Funnel/ngrok tunnels, startup-service installation/removal, or destructive cleanup. A request for local development does not authorize these actions. Use PORTLESS_SYNC_HOSTS=0 when hosts writes are not approved. In non-interactive environments, first-run prompts fail rather than granting permission; pre-start only an approved proxy configuration.

--force kills the existing process and takes over its route. prune terminates orphaned process groups, and prune --force uses SIGKILL. Do not use them without checking ownership and approval. clean also removes startup services and trust entries; it is not routine project cleanup.

Never print or commit TLS private keys or ngrok tokens. Let the user configure authentication through the provider's private credential workflow. Do not disable TLS verification to resolve proxy errors.

Why Portless?

Local dev with port numbers is fragile. Portless fixes that by giving each dev server a stable, named .localhost URL.

Problem	With Ports	With Portless
Port conflicts	Two projects on :3000 = EADDRINUSE	Auto-assigned ports, named URLs - no collisions
Memorizing ports	"Was the API on 3001 or 8080?"	Always `https://api.localhost`
Wrong app on refresh	Stop one server, start another on same port = confusion	Named URLs eliminate this
Monorepo chaos	Every service needs a unique port	Distinct hostnames for each service
Agent confusion	AI agents guess/hardcode wrong ports	`https://myapp.localhost` is deterministic
Cookie/storage clashes	Cookies bleed across ports on localhost	Each `.localhost` subdomain gets its own scope
Hardcoded config	CORS, OAuth, .env break when ports change	URLs are stable across restarts
Sharing URLs	"What port is that on?" in Slack	Everyone uses the same named URL
Browser history	`localhost:3000` history is a jumble	Named URLs keep things organized

Installation

# Global (recommended)
npm install -g portless

# Or as a project dev dependency
npm install -D portless

Requires Node.js 24+ and OpenSSL for certificate generation. Install globally or as a project dependency; do not use a one-off npx/pnpm dlx download. A local package may be invoked through package scripts or npx portless without downloading it.

Usage

Invoke via skill command or use CLI directly:

# Via skill command
/portless-local <NAME> <COMMAND> [OPTIONS]

# Or use CLI directly
portless <NAME> <COMMAND> [OPTIONS]

Commands

Run an App

portless run [--name <name>] <cmd> [args...]   # Infers name from package.json, git root, or directory
portless <name> <cmd> [args...]                # Explicit name, no inference

portless run infers the project name from package.json, git root, or directory name. Use --name to override the inferred name while still applying worktree prefixes.

Flag	Description
`--name <name>`	Override the inferred base name (worktree prefix still applies). Only for `portless run`.
`--app-port <number>`	Use a fixed port for the app instead of auto-assignment. Also configurable via `PORTLESS_APP_PORT`.
`--force`	Kill the existing process and take over its route; requires ownership checks and approval

Examples:

portless run next dev                    # Infer name from project
portless run --name myapp next dev       # Override inferred name
portless myapp next dev                  # Explicit name
portless api pnpm start                  # API service
portless docs.myapp next dev             # Subdomain

Get a Service URL

portless get <name>

Print the URL for a service. Useful for wiring services together in scripts or env vars:

BACKEND_URL=$(portless get backend)

Applies worktree prefix detection by default. Use --no-worktree to skip it.

Alias (Static Routes)

portless alias <name> <port>              # Register a static route
portless alias <name> <port> --force     # Force override existing
portless alias --remove <name>            # Remove the alias

Register a route for a service not managed by portless (e.g. a Docker container). Aliases persist across stale-route cleanup.

portless alias my-postgres 5432     # -> https://my-postgres.localhost
portless alias redis 6379           # -> https://redis.localhost
portless alias --remove my-postgres # Remove the alias

List Routes

portless list

Shows active routes and their assigned ports.

Trust the CA

portless trust

Adds the portless certificate authority to your system trust store. Required once for HTTPS with auto-generated certs.

If you skipped the trust prompt on first run, run portless trust to add the CA later.

HTTPS & HTTP/2

The CLI enables HTTPS on port 443 by default. That covers OAuth callbacks, secure cookies, and HTTP/2. Pass --no-tls or set PORTLESS_HTTPS=0 only when the app should stay on plain HTTP.

When HTTPS stays on, the first run may generate a local CA and server certificates. Run portless trust if the host or browser must trust that certificate.

Custom certificates: Use your own certs (e.g., from mkcert):

portless proxy start --cert ./cert.pem --key ./key.pem

Disable HTTPS: HTTPS on port 443 is the CLI default. portless proxy start --no-tls or PORTLESS_HTTPS=0 selects plain HTTP on port 80. Do not put --no-tls after the app command; portless forwards those arguments to the child process.

portless proxy start --no-tls
PORTLESS_HTTPS=0 portless myapp next dev

Clean Up

portless clean

Stops the proxy, removes the CA from OS trust store, deletes allowlisted files under ~/.portless, the system state directory, and removes the portless block from /etc/hosts. May prompt for elevated privileges.

Proxy Control

Start Proxy

portless proxy start

Flag	Description
`-p, --port <number>`	Proxy port (default: 443, or 80 with `--no-tls`).
`--no-tls`	Disable HTTPS (plain HTTP on port 80).
`--https`	Enable HTTPS (CLI default; kept for compatibility).
`--lan`	Enable LAN mode (mDNS `.local` domains for real device testing)
`--ip <address>`	Override auto-detected LAN IP (use with `--lan`)
`--tld <tld>`	Use a custom TLD instead of `.localhost` (e.g. `.test`)
`--cert <path>`	Custom TLS certificate
`--key <path>`	Custom TLS private key
`--foreground`	Run in foreground instead of daemon mode

Stop Proxy

portless proxy stop

LAN Mode

Access services from phones and other devices on the same WiFi via mDNS (.local domains):

portless proxy start --lan
portless proxy start --lan --https
portless proxy start --lan --ip 192.168.1.42   # Manual IP override

Make it permanent by adding export PORTLESS_LAN=1 to your shell profile. Portless also remembers LAN mode via proxy.lan, so a stopped LAN proxy starts in LAN mode again.

Framework notes for LAN:

Next.js: Add allowedDevOrigins: ['myapp.local', '*.myapp.local'] to next.config.js
Vite / React Router / SvelteKit / Astro: Handled automatically via __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS
Expo / React Native: Add NSAllowsLocalNetworking to app.json for iOS ATS

Hosts

portless hosts sync     # Add current routes to /etc/hosts
portless hosts clean    # Remove portless entries from /etc/hosts

Auto-sync is on by default. Set PORTLESS_SYNC_HOSTS=0 to disable.

Bypass Portless

PORTLESS=0 pnpm dev

Runs the command directly without the proxy.

Info

portless --help
portless --version
portless doctor    # Read-only diagnostics for proxy, DNS, trust, routes, and LAN prerequisites

Sharing and Startup Services

Only run these after approval for the stated exposure or persistent system change:

portless myapp --tailscale next dev   # Tailnet; requires connected Tailscale CLI and HTTPS certificates
portless myapp --funnel next dev      # Public internet; requires Funnel enabled for tailnet and node
portless myapp --ngrok next dev       # Public internet; requires authenticated ngrok CLI
portless service status              # Inspect installed service configuration
portless service install             # Persist proxy at OS startup; may require administrator privileges
portless service uninstall           # Remove startup service

Tailscale and ngrok registrations are removed when the app exits. PORTLESS_TAILSCALE, PORTLESS_FUNNEL, and PORTLESS_NGROK can enable sharing by default; inspect them before starting an app. Startup services save their options in launchd, systemd, or Task Scheduler, and may run as root or SYSTEM.

Common Use Cases

1. Basic Development Server

# Next.js
portless myapp next dev
# -> https://myapp.localhost

# Vite (auto-detected, --port injected)
portless myapp vite dev
# -> https://myapp.localhost

# Express
portless api node server.js
# -> https://api.localhost

2. Multiple Services with Subdomains

# API service
portless api.myapp pnpm start
# -> https://api.myapp.localhost

# Documentation
portless docs.myapp next dev
# -> https://docs.myapp.localhost

# Admin dashboard
portless admin.myapp npm run dev
# -> https://admin.myapp.localhost

3. Use in package.json

{
	"scripts": {
		"dev": "portless myapp next dev",
		"dev:http": "PORTLESS_HTTPS=0 portless myapp next dev"
	}
}

4. Git Worktree Support

portless run auto-detects git worktrees. The branch name is prepended as a subdomain:

# Main worktree
portless run next dev
# -> https://myapp.localhost

# Linked worktree on branch "fix-ui"
portless run next dev
# -> https://fix-ui.myapp.localhost

Put portless run in your package.json once and it works everywhere - no collisions, no --force.

5. Custom TLD

# Use .test TLD instead of .localhost
portless proxy start --tld test
portless myapp next dev
# -> https://myapp.test

Recommended TLDs:

.localhost - Default, auto-resolves to 127.0.0.1 in most browsers
.test - IANA-reserved, no collision risk (recommended)
Avoid: .local (conflicts with mDNS/Bonjour), .dev (Google-owned, forces HTTPS via HSTS)

6. Static Aliases for External Services

# Docker container running Postgres
portless alias my-postgres 5432
# -> https://my-postgres.localhost

# Redis server
portless alias redis 6379
# -> https://redis.localhost

7. Wire Services Together

# Get backend URL for frontend env
BACKEND_URL=$(portless get backend)
echo "VITE_API_URL=$BACKEND_URL" > .env.local
portless frontend vite dev

How It Works

Browser (myapp.localhost) -> HTTPS Proxy (port 443) -> App (random port 4000-4999)

Portless runs an HTTPS reverse proxy on port 443 (or HTTP on port 80 with --no-tls)
Each app registers a route mapping hostname to assigned port
Requests to https://<name>.localhost are proxied to the app
Default HTTPS: auto-generates a local CA. Run portless trust when the host or browser must trust it
Auto-elevates with sudo on macOS/Linux for port binding

Framework Support

Portless auto-detects and configures:

Framework	Support	Notes
Next.js	✅ Native	Respects PORT env var
Express	✅ Native	Respects PORT env var
Nuxt	✅ Native	Respects PORT env var
Vite	✅ Injected	Auto-adds `--port` flag
Astro	✅ Injected	Auto-adds `--port` flag
React Router	✅ Injected	Auto-adds `--port` flag
Angular	✅ Injected	Auto-adds `--port` and `--host`
Expo	✅ Injected	Auto-adds `--port` and `--host`
React Native	✅ Injected	Auto-adds `--port` and `--host`

Configuration

Zero-config and Workspaces

Bare portless runs the package's dev script with an inferred name. An optional portless.json or package.json portless key can set name, script, appPort, and proxy (false for non-proxied tasks).

{
  "apps": {
    "apps/web": { "name": "myapp" },
    "apps/api": { "name": "api.myapp" }
  }
}

From a workspace root, portless discovers packages in pnpm-workspace.yaml or package.json workspaces and starts their dev scripts. Unlisted packages use inferred names. Use --script start for a different script. Readable turbo.json or turbo.jsonc preserves Turbo task ordering; root "turbo": false selects direct spawning.

Precedence: CLI flags > package.json portless key > portless.json app entry > defaults. To avoid recursion when dev runs portless, put the real command in dev:app and configure "portless": { "script": "dev:app" }.

Strict routing is the default. proxy start --wildcard allows unregistered child subdomains to fall back to the most specific registered parent. Multiple --tld flags (or comma-separated PORTLESS_TLD) support single- and multi-segment domains. Review these routing changes before use.

Environment Variables

Variable	Description	Default
`PORTLESS_PORT`	Proxy port	443; 80 with `--no-tls`
`PORTLESS_HTTPS`	Set to `0` to disable HTTPS (same as `--no-tls`)	on
`PORTLESS_LAN`	Set to `1` to always enable LAN mode (mDNS `.local` domains)	off
`PORTLESS_TLD`	One or more comma-separated TLDs (e.g. `localhost,dev.example.com`)	localhost
`PORTLESS_WILDCARD`	Set to `1` for parent-route fallback	off
`PORTLESS_LAN_IP`	Pin a LAN IP instead of auto-detection	auto-detected
`PORTLESS_TAILSCALE`	Share apps on the tailnet; requires approval	off
`PORTLESS_FUNNEL`	Share apps publicly; requires approval	off
`PORTLESS_NGROK`	Share apps publicly through ngrok; requires approval	off
`PORTLESS_APP_PORT`	Use a fixed port for the app (skip auto-assignment)	random 4000-4999
`PORTLESS_SYNC_HOSTS`	Set to `0` to disable auto-sync of `/etc/hosts`	on
`PORTLESS_STATE_DIR`	Override the state directory	see below
`PORTLESS`	Set to `0` to bypass the proxy	enabled

State Directory

Portless stores state (routes, PID file, port file, TLS marker) in ~/.portless. Under sudo, this remains the invoking user's home so apps and the proxy share registrations.

Override with PORTLESS_STATE_DIR.

State Files

File	Purpose
`routes.json`	Maps hostnames to ports
`routes.lock`	Prevents concurrent writes
`proxy.pid`	PID of the running proxy
`proxy.port`	Port the proxy is listening on
`proxy.log`	Proxy daemon log output
`proxy.lan`	Remembers LAN mode and stores the last known LAN IP

Port Assignment

Apps get a random port in the 4000-4999 range. Portless sets PORT and usually HOST before running your command. Most frameworks respect PORT automatically. For frameworks that ignore it (Vite, Astro, React Router, Angular, Expo, React Native), portless auto-injects the right --port flag and, when needed, a matching --host flag.

Injection applies to recognized server commands, including VitePlus, and can reach through simple package scripts. It skips build/test/check commands, compound shell commands, env prefixes, script delegation, option terminators, comments, and ambiguous runner flags. Those scripts must set their own port. Expo's --localhost, --lan, and --tunnel modes are preserved.

Portless sets NODE_EXTRA_CA_CERTS for child Node.js processes. For a separate process that must trust the local CA, use NODE_EXTRA_CA_CERTS=~/.portless/ca.pem rather than disabling certificate verification.

Troubleshooting

Port 443 permission denied

# Only after explicit approval for elevation:
sudo portless proxy start

# Or configure an approved unprivileged proxy before the app starts.
# Flags after the child command are forwarded to Next.js, which rejects --no-tls.
PORTLESS_HTTPS=0 PORTLESS_PORT=8080 portless myapp next dev

When sudo is unavailable, portless falls back to port 1355. Check the actual URL rather than assuming 443. Use portless doctor first for routing, DNS, or trust failures. For cross-app proxy loops, set changeOrigin: true in the forwarding proxy so the Host header matches the target route.

Certificate warning

Trust the local CA on first run. Run portless trust if needed.

Name collision

# Each worktree gets unique subdomain automatically
# Or use different names:
portless myapp-v2 next dev

Comparison

Tool	Type	URLs	Use Case
portless	Local proxy	`https://myapp.localhost`	Clean local dev URLs
ngrok	Public tunnel	`https://random.ngrok.io`	Share with others
cloudflared	Public tunnel	`https://myapp.trycloudflare.com`	Share with others

portless.sh - Official documentation
vercel-labs/portless - Official skill for Claude Code