Port Management

Overview

Superset does not assign per-workspace port ranges. It discovers listening ports from processes running in each workspace and lets you manage them from the UI.

Features

• View active ports - See which processes are using which ports
• Kill processes - Stop a process by clicking its port
• Workspace grouping - Ports are grouped by the workspace that owns the process
• Terminal focus - Select a port to jump back to the terminal that owns it
• Browser actions - Open local web servers in the in-app browser or externally from the port action

Port Labels

Add friendly names to automatically detected ports with a workspace configuration file. Useful for:

• Providing meaningful labels for your team
• Making common dev-server ports easier to scan in the UI

Create .superset/ports.json in your repository:

{
  "ports": [
    { "port": 3000, "label": "Frontend Dev Server" },
    { "port": 8080, "label": "API Server" },
    { "port": 5432, "label": "PostgreSQL" }
  ]
}

Fields:

• port - Port number (1-65535)
• label - Display text shown in tooltip

Behavior:

• Dynamic port discovery is still authoritative
• ports.json only labels ports that Superset already detects as listening
• Ports without a matching label still appear
• Label entries for ports that are not currently listening are ignored
• Each workspace reads labels from its own worktree's file
• Changes are detected automatically
• Ports can be opened at localhost:PORT from the browser action

Error Handling:

If ports.json is malformed:

• Labels from that file are ignored until fixed
• Detected ports still appear without those labels

Tips:

• Commit .superset/ports.json to share port labels with your team
• Pro tip: If you want deterministic per-workspace port ranges, implement it in setup/teardown scripts by reserving a range in a shared file (for example ~/.superset/port-allocations.json) during setup and releasing it during teardown. See this repo's examples: .superset/setup.sh and .superset/teardown.sh.

Discovery and Updates

Port discovery runs in each host server, not in the desktop renderer. The host server watches terminal process trees, scans for listening ports, resolves any matching port label, and publishes port:changed events when ports appear or disappear.

The desktop sidebar keeps one ports query per online host. It patches that cached host snapshot from port events, batching bursts so updates stay responsive without refetching every time a port changes. A slower fallback refetch still runs so the UI recovers if an event is missed during reconnect.