Proxy Rules

How Routing Works

The PortPilot proxy uses the HTTP Host header to determine which project a request is for. When you visit https://my-app.test, the proxy:

1. Extracts my-app.test from the Host header
2. Looks up the project name (my-app) in the config
3. Finds the assigned port (e.g., 3001)
4. Forwards the request to http://localhost:3001

The Hosts File

For your browser to resolve .test domains to localhost, PortPilot adds entries to your system's hosts file. Run portpilot sync to update these entries:

# Hosts file entries managed by PortPilot
# PortPilot Start
127.0.0.1 my-app.test
127.0.0.1 my-api.test
127.0.0.1 my-blog.test
# PortPilot End

WebSocket Support

The proxy includes WebSocket upgrade handlers, which means Hot Module Replacement (HMR) works seamlessly. Your development experience with frameworks like Next.js, Vite, and webpack-dev-server will work exactly as expected.

Proxy Commands

Control the proxy with these commands:

# Run proxy in foreground (see logs in terminal)
portpilot proxy
# Run proxy in background (daemon mode)
portpilot proxy -d
# Stop the background proxy
portpilot proxy stop
# Check if proxy is running
portpilot proxy status
# View proxy logs
portpilot proxy logs
# Force HTTP to HTTPS redirect
portpilot proxy --https-redirect

HTTPS Redirect

By default, both HTTP (port 80) and HTTPS (port 443) work independently. If you want to force all HTTP traffic to redirect to HTTPS, use the --https-redirect flag:

portpilot proxy -d --https-redirect