Port Management

Automatic Port Assignment

When you register a project, PortPilot automatically assigns an available port starting from 3001. This eliminates the common EADDRINUSE error when multiple projects try to use the same port.

portpilot add my-app
# ✓ Added my-app
#   Port: 3001
#   URL: https://my-app.test

Specifying a Custom Port

If you need a specific port for your project, use the --port flag:

portpilot add my-api --port 4000

Viewing Port Assignments

Use the list command to see all projects and their port assignments:

portpilot list
# ID  Name       Port  URL                  Status
# 1   my-app     3001  https://my-app.test  running
# 2   my-api     4000  https://my-api.test  stopped
# 3   my-blog    3002  https://my-blog.test running

How Ports Are Used

When you start a project, PortPilot launches your dev server with the assigned port. The port is passed to your dev command using the appropriate flag for your framework:

• Next.js: npm run dev -- -p 3001
• Vite: npm run dev -- --port 3001
• Create React App: PORT=3001 npm start

The Proxy Ports

The PortPilot proxy itself runs on ports 80 (HTTP) and 443 (HTTPS). These are the standard web ports, which is why the proxy requires administrator/sudo access to start.

When your browser requests https://my-app.test, the request goes to the proxy on port 443, which then forwards it to your dev server on its assigned port (e.g., 3001).