peakroute

peakroute

[!NOTE] 📌 Fork Notice: This is a continuation fork of vercel-labs/portless. We maintain and extend the project with additional features and platform support.

[!IMPORTANT] 🪟 Windows Support Added! This fork includes full Windows support alongside macOS and Linux. No platform limitations!

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

- "dev": "next dev"              # http://localhost:3000
+ "dev": "peakroute myapp next dev"  # http://myapp.localhost:1355

Quick Start

# Install
npm install -g peakroute

# Start the proxy (once, no sudo needed)
peakroute proxy start

# Run your app (auto-starts the proxy if needed)
peakroute myapp next dev
# -> http://myapp.localhost:1355

The proxy auto-starts when you run an app. You can also start it explicitly with peakroute proxy start.

Why

Local dev with port numbers is fragile:

• Port conflicts -- two projects default to the same port and you get EADDRINUSE
• Memorizing ports -- was the API on 3001 or 8080?
• Refreshing shows the wrong app -- stop one server, start another on the same port, and your open tab now shows something completely different
• Monorepo multiplier -- every problem above scales with each service in the repo
• Agents test the wrong port -- AI coding agents guess or hardcode the wrong port, especially in monorepos
• Cookie and storage clashes -- cookies set on localhost bleed across apps on different ports; localStorage is lost when ports shift
• Hardcoded ports in config -- CORS allowlists, OAuth redirect URIs, and .env files all break when ports change
• Sharing URLs with teammates -- "what port is that on?" becomes a Slack question
• Browser history is useless -- your history for localhost:3000 is a jumble of unrelated projects

Peakroute fixes all of this by giving each dev server a stable, named .localhost URL that both humans and agents can rely on.

Usage

# Basic
peakroute myapp next dev
# -> http://myapp.localhost:1355

# Subdomains
peakroute api.myapp npm start
# -> http://api.myapp.localhost:1355

peakroute docs.myapp next dev
# -> http://docs.myapp.localhost:1355

In package.json

{
  "scripts": {
    "dev": "peakroute myapp next dev"
  }
}

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

How It Works

flowchart TD
    Browser["Browser<br/>myapp.localhost:1355"]
    Proxy["peakroute proxy<br/>(port 1355)"]
    App1[":4123<br/>myapp"]
    App2[":4567<br/>api"]

    Browser -->|port 1355| Proxy
    Proxy --> App1
    Proxy --> App2

• Start the proxy -- auto-starts when you run an app, or start explicitly with peakroute proxy start
• Run apps -- peakroute <name> <command> assigns a free port and registers with the proxy
• Access via URL -- http://<name>.localhost:1355 routes through the proxy to your app

Apps are assigned a random port (4000-4999) via the PORT and HOST environment variables. Most frameworks (Next.js, Express, Nuxt, etc.) respect these automatically. For frameworks that ignore PORT (Vite, Astro, React Router, Angular), peakroute auto-injects the correct --port and --host flags.

HTTP/2 + HTTPS

Enable HTTP/2 for faster dev server page loads. 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.

# Start with HTTPS/2 -- generates certs and trusts them automatically
peakroute proxy start --https

# First run prompts for sudo once to add the CA to your system trust store.
# After that, no prompts. No browser warnings.

# Make it permanent (add to .bashrc / .zshrc)
export PEAKROUTE_HTTPS=1
peakroute proxy start    # HTTPS by default now

# Use your own certs (e.g., from mkcert)
peakroute proxy start --cert ./cert.pem --key ./key.pem

# If you skipped sudo on first run, trust the CA later
sudo peakroute trust

Commands

peakroute <name> <cmd> [args...]  # Run app at http://<name>.localhost:1355
peakroute list                    # Show active routes
peakroute trust                   # Add local CA to system trust store
peakroute alias <host> <port>    # Register external service (e.g., Docker)
peakroute alias remove <host>     # Remove an external route

# Disable peakroute (run command directly)
PEAKROUTE=0 bun dev              # Bypasses proxy, uses default port
# Also accepts PEAKROUTE=skip

# Proxy control
peakroute proxy start             # Start the proxy (port 1355, daemon)
peakroute proxy start --https     # Start with HTTP/2 + TLS
peakroute proxy start -p 80       # Start on port 80 (requires sudo)
peakroute proxy start --foreground  # Start in foreground (for debugging)
peakroute proxy stop              # Stop the proxy

# Options
-p, --port <number>              # Port for the proxy (default: 1355)
                                 # Ports < 1024 require sudo
--https                          # Enable HTTP/2 + TLS with auto-generated certs
--cert <path>                    # Use a custom TLS certificate (implies --https)
--key <path>                     # Use a custom TLS private key (implies --https)
--no-tls                         # Disable HTTPS (overrides PEAKROUTE_HTTPS)
--foreground                     # Run proxy in foreground instead of daemon
--force                          # Override a route registered by another process

# Environment variables
PEAKROUTE_PORT=<number>           # Override the default proxy port
PEAKROUTE_HTTPS=1                 # Always enable HTTPS
PEAKROUTE_STATE_DIR=<path>        # Override the state directory

# Info
peakroute --help                  # Show help
peakroute --version               # Show version

State Directory

Peakroute stores its state (routes, PID file, port file) in a directory that depends on the proxy port:

• Port < 1024 (sudo required): /tmp/peakroute -- shared between root and user processes
• Port >= 1024 (no sudo): ~/.peakroute -- user-scoped, no root involvement

Override with the PEAKROUTE_STATE_DIR environment variable if needed.

External Services (Docker, etc.)

Use the peakroute alias command to register routes for services not spawned by peakroute, such as Docker containers or other external processes:

# Register a Docker container running on port 3000
peakroute alias mydocker.localhost 3000

# Now access it at http://mydocker.localhost:1355

# Remove the alias when done
peakroute alias remove mydocker.localhost

Aliases are marked with [external] in the route list and are never cleaned up as "stale" since they don't have an associated process PID.

peakroute list
# -> http://mydocker.localhost:1355 -> localhost:3000 (pid 0) [external]

Git Worktree Support

Peakroute automatically detects when you're running inside a Git Worktree and prepends the branch name as a subdomain prefix. This gives each worktree a unique URL without any configuration changes.

# In a worktree on branch feat/login
peakroute myapp next dev
# -> http://feat-login.myapp.localhost:1355

# In a worktree on branch fix/auth-bug
peakroute api next dev
# -> http://fix-auth-bug.api.localhost:1355

The branch name is sanitized for use as a hostname (slashes become hyphens, invalid characters are removed).

Development

This repo is a Bun workspace monorepo using Turborepo. The publishable package lives in packages/peakroute/.

bun install          # Install all dependencies
bun run build        # Build all packages
bun run test         # Run tests
bun run test:coverage # Run tests with coverage
bun run test:watch   # Run tests in watch mode
bun run lint         # Lint all packages
bun run typecheck    # Type-check all packages
bun run format       # Format all files with Prettier

Proxying Between Peakroute Apps

If your frontend dev server (e.g. Vite, webpack) proxies API requests to another peakroute app, make sure the proxy rewrites the Host header. Without this, the proxy sends the original Host header, causing peakroute to route the request back to the frontend in an infinite loop.

Vite (vite.config.ts):

server: {
  proxy: {
    "/api": {
      target: "http://api.myapp.localhost:1355",
      changeOrigin: true,  // Required: rewrites Host header to match target
      ws: true,
    },
  },
}

webpack-dev-server (webpack.config.js):

devServer: {
  proxy: [{
    context: ["/api"],
    target: "http://api.myapp.localhost:1355",
    changeOrigin: true,  // Required: rewrites Host header to match target
  }],
}

Peakroute detects this misconfiguration and responds with 508 Loop Detected along with a message pointing to this fix.

Requirements

• Node.js 20+
• macOS, Linux, or Windows