Port Warden

Local TCP port awareness on your Stream Deck. See what is listening, identify the process holding a development port, and release your workspace without switching to a terminal. Built for macOS and Windows by Dloper.

1. Overview & Requirements

Port Warden continuously inspects local TCP listening sockets and presents them on your Stream Deck keypad and Stream Deck + dials. It is designed for software developers, devops engineers, and local server administrators who need to track and manage local web servers, development environments (Vite, Next.js, Node, Django, Rails), Docker containers, and database listeners.

2. Actions & Usage

Single Port Warden

Assign a key to a specific port you use frequently (such as 3000, 5173, 8000, or 8080).

• Status Display: Shows whether the port is free or occupied. When occupied, displays process name, process ID (PID), and memory consumption if available.
• Press to Terminate: Briefly pressing an occupied key initiates termination of the eligible listening process. Choose between Graceful mode (attempts standard graceful shutdown before escalating) or Force mode (terminates immediately).
• Press to Open Browser: Briefly pressing a free key opens http://localhost:[port] in your default browser.
• Long-Press: Hold for at least 1.2 seconds to open the configured browser URL, copy the PID to clipboard, or do nothing.

Stack Radar

Monitor your complete development stack on a single key by entering up to four comma-separated ports (e.g. 3000, 5001, 8000, 8080).

• Multi-Port Grid: Shows real-time free/occupied status for each configured port simultaneously.
• Cycle Ports: Tap the key to cycle focus through currently occupied ports.
• Two-Step Confirmation: To stop all eligible stack listeners, hold the key for at least 1.5 seconds, then press again within 5 seconds to confirm.

Dial Inspector (Stream Deck +)

Place Dial Inspector on an encoder dial on Stream Deck +.

• Rotate: Browse all detected TCP listeners on your computer.
• Touch Strip: Displays the selected port number, process name, PID, and status.
• Push Dial / Touch Strip: Press the dial or tap the right side of the touch strip to stop the selected eligible listener.
• Hold Dial (1.2s): Opens the selected local address in your default web browser.

3. Protection & Safety Guardrails

Port Warden includes strict built-in safety boundaries to protect your operating system and prevent accidental service disruption:

• Privileged Port Protection: System ports below 1024 cannot be terminated by Port Warden.
• Explicitly Protected Ports: Ports 5000 (macOS AirPlay Receiver) and 7000 (system services) are protected against termination.
• Protected System Processes: Core operating system daemons and critical background services are blocked from termination.
• Ambiguity Protection: If a port has multiple listeners or process ownership cannot be verified, Port Warden will refuse the termination request.
• Local & Private: All port scanning and process inspection occur strictly on your local computer via native OS APIs. No telemetry or network packets are sent outside your machine.

4. Status Indicators & Troubleshooting