Architecture

How It Works

PortPilot acts as a reverse proxy between your browser and your dev servers. Here's the flow:

┌─────────────────────────────────────────┐
│            Browser Request              │
│       https://my-store.test             │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│     PortPilot Proxy (:80 / :443)        │
│   Routes based on Host header           │
│   SNI for per-domain SSL certs          │
└────────────────────┬────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────┐
│       Dev Server (localhost:3001)       │
│            Next.js / Vite / etc         │
└─────────────────────────────────────────┘

Key Components

1. Hosts File

PortPilot adds entries to your system's hosts file to route .test domains to localhost:

# PortPilot Start
127.0.0.1 my-store.test
127.0.0.1 my-api.test
127.0.0.1 my-blog.test
# PortPilot End

2. Port Assignment

Each project gets a unique port starting from 3001. Ports are automatically assigned when you register a project and stored in the configuration.

3. Reverse Proxy

The proxy listens on ports 80 (HTTP) and 443 (HTTPS). When a request comes in, it:

• Extracts the hostname from the request (e.g., my-store.test)
• Looks up which port that project is running on
• Forwards the request to localhost:PORT
• Returns the response to the browser

4. SSL/HTTPS

PortPilot uses mkcert to generate locally-trusted SSL certificates. Each project gets its own certificate, and the proxy uses SNI (Server Name Indication) to serve the correct certificate based on the requested domain.

5. Process Manager

When you start a project, PortPilot spawns the dev server as a detached process. PIDs are tracked so you can stop or restart servers later.

Configuration Storage

Configuration is stored at different locations depending on your platform:

• Windows: %APPDATA%/portpilot-nodejs/config.json
• macOS: ~/Library/Application Support/portpilot-nodejs/config.json
• Linux: ~/.config/portpilot-nodejs/config.json

SSL certificates are stored in ~/.portpilot/certs/.

Supported Frameworks

PortPilot auto-detects and configures these frameworks: