Ports
Find listening ports, inspect process and related resources, and run allowlisted actions.
What this is
PortPilot’s core object is a listening binding: protocol, bind address, and port, plus the process that owns it.
You see what is actually listening instead of guessing from config files — including Docker publishes and reverse-proxy routes when they are detected.
Prerequisites
Agent running. Pairing required only for the website fleet view.
Where to look
- Desktop: Ports
- Website: Ports (fleet table) and Machines → port detail
- CLI:
portpilot portsandportpilot port <n>
Search from the website search box or Cmd+K filters (for example port:3000, docker:yes). Diagnose and filter work when the machine is online.
Port detail includes process, service (when identified), health, history, Docker/proxy/tunnel relations, and controls you are entitled to run.
Port actions
Only these controls exist. There is no arbitrary shell. Confirmation depends on your automation preference (Safe / Smart / Developer) on the website.
| Action | Label | When to use | Risk | Confirmation |
|---|---|---|---|---|
| Kill | Kill process | Stop the owning process | High — the process exits | Usually yes |
| Restart service | Restart service | Bounce an identified OS service | Medium | Often |
| Start / stop service | Start service / Stop service | Service mapped to the port | Stop is high impact | Stop usually yes |
| Firewall allow | Allow TCP inbound | Open inbound TCP (Pro) | Medium — exposes the port | Often |
| Firewall block | Block TCP inbound | Block inbound TCP (Pro) | High — can cut remote access | Usually yes |
| Remove PP rule | Remove PortPilot rule | Undo a PortPilot firewall rule | Medium | Often |
| Expose | Expose (tunnel) | Public ngrok URL (Pro) | High — public internet | Usually yes |
| Stop / restart tunnel | Stop tunnel / Restart tunnel | Tear down or recycle ngrok | Medium | Often |
Bare PID restart without a service identity is not supported. Docker containers cannot be started or stopped from PortPilot.
Expected result
Bindings refresh while the agent is running. History survives agent restarts in local SQLite.
Common problems
| Symptom | Recovery |
|---|---|
| Port not appearing | Process not listening; rescan; portpilot ports on the host |
| Stale rows | Machine offline — controls will not queue |
| Action missing | Entitlement (firewall/tunnel are Pro/Cloud) or helper down |
| Kill failed | Process already exited, or ProcessGuard mismatch — rescan |
Related: Processes, Services, Firewall, Tunnels, Docker, Reverse proxies, Diagnostics.