Portview README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Portview listing page.
portview
portview lists ports and the processes using them on Linux, macOS, and Windows. It shows process names, commands, memory usage, and uptime. You can inspect a port, stop its process, or monitor changes in an interactive terminal UI.
It also supports Docker, remote hosts over SSH, and an MCP server for coding agents.
Install
Homebrew:
Linux / macOS:
Windows (PowerShell):
Or use cargo install portview, or download a binary from
Releases.
What it does
Features
Scan
--all includes non-listening connections, with one row per connection.
--wide shows full commands. --json produces JSON output for scripts.
Ports whose owner can't be resolved are still listed, with - in the columns that can't be filled. That happens for another user's process without sudo, and for sockets like TIME_WAIT that outlive the process that opened them.
The scan, doctor, and MCP examples below are real output, captured by
demo/record.shinside an isolated namespace — which is why the user isrootand the paths are/opt/app. The Docker example is illustrative, since it needs a running daemon.
MCP server (for AI agents)
portview mcp provides port queries, diagnostics, and process termination over
the Model Context Protocol using stdio.
To register it with Claude Code:
Or configure it manually:
| Tool | What it does |
|---|---|
list_ports | List listening ports with available process details |
inspect_port | Inspect a port, including process working directories and descendants |
find_process | Find ports by process name or command substring |
doctor | Check for conflicts, wildcard exposure, connection buildup, and high memory usage |
diff_ports | Report ports that opened, closed, or changed owner since a baseline |
kill_port | Terminate processes using a port; dry_run previews the targets. Marked destructive to the client |
The MCP server is included in the portview binary. Pass --read-only to disable
the kill_port tool:
Listed in the MCP Registry as
mcp-name: io.github.Mapika/portview.
Watch mode (interactive TUI)
| Key | Action |
|---|---|
j/k, ↑/↓ | Navigate rows |
Enter | Inspect port (full command, cwd, children, connections) |
d/D | Kill process or manage Docker container |
/ | Filter across all columns |
←/→, r | Cycle sort column, reverse direction |
t | Toggle process tree view |
a | Toggle all/listening-only |
q | Quit |
Tree view (t): Groups child processes under their parents.
Detail view (Enter): Shows the full unwrapped command, working directory, child process list with ports, and open connections (in --all mode).
Doctor
portview doctor checks for port conflicts, wildcard bindings, connection
buildup, and high memory usage:
| Check | Flags |
|---|---|
| Port conflicts | Multiple PIDs bound to the same port |
| Wildcard exposure | Databases (postgres, redis, mysql, mongod, …) listening on 0.0.0.0 |
| Docker-host conflicts | A container publishing a port the host already uses |
| Connection buildup | High counts of TIME_WAIT or CLOSE_WAIT connections on one port; these do not by themselves establish a leak |
| High memory usage | Listening processes using more than 1 GB of resident memory |
Docker is auto-detected. portview doctor --json for scripting (exit code 1 on errors).
In CI
The GitHub Action runs doctor and can fail a workflow on errors or warnings:
It annotates each finding inline on the run, writes a summary table, and exposes
findings (JSON), count, errors, and warnings as step outputs:
Set install: false if portview is already on PATH. Linux and macOS runners.
SSH remote mode
Inspect ports on a remote host over SSH:
Kill actions in the remote TUI are forwarded over SSH.
If portview is not installed on the remote host, SSH mode collects data using
ss and ps, or lsof and ps where ss is unavailable. This requires a
POSIX shell and the collection tools on the remote host.
Use --agentless to collect data this way even when portview is installed on
the remote host. It supports scans, port inspection, process search,
diagnostics, and watch mode.
Run diagnostics on the collected data:
This uses the same diagnostic checks as local mode. The Docker check is skipped because agentless mode does not query remote containers.
Watch remote ports, with process termination available in the TUI:
Watch mode collects updates through a single persistent SSH connection.
Docker integration
Use --docker to include ports published by Docker containers:
Container-only rows have no host process, so PID, UPTIME, and MEM render as -.
In watch mode, press d on a Docker row to stop or restart the container, or
follow its logs.
JSON output
Custom colors
Columns: port, proto, pid, user, process, uptime, mem, command. Use --no-color to disable.
How it works
Local port and process data comes from OS interfaces:
| Field | Linux | macOS | Windows |
|---|---|---|---|
| Ports | /proc/net/tcp{,6}, udp{,6} | proc_pidfdinfo | GetExtendedTcp/UdpTable |
| PID | inode→pid via /proc/*/fd/ | proc_listpids | Included in socket table |
| Process | /proc/<pid>/exe | proc_pidpath | QueryFullProcessImageNameW |
| Memory | /proc/<pid>/status VmRSS | proc_pidinfo | K32GetProcessMemoryInfo |
| Uptime | /proc/<pid>/stat | proc_pidinfo | GetProcessTimes |
On Linux, portview reads the executable name from /proc/<pid>/exe.
The thread name in /proc/<pid>/comm can be changed by the runtime and is
limited to 15 bytes.
Docker integration uses the docker CLI. SSH mode uses the system ssh
client to run portview or the agentless collection tools on the remote host.
MCP mode uses newline-delimited JSON-RPC 2.0 on stdin/stdout.
Building from source
Requires Rust 1.85+ (edition 2024). Shell completions and man page are generated at build time.
The repository includes a Dockerfile. To inspect the host from a container,
share the host's network and PID namespaces:
Contributing
See CONTRIBUTING.md for development setup and guidelines, and demo/README.md for regenerating the recordings.
Changes should type-check on all three platforms, not just yours:
Limitations
- Linux: Other users' ports are listed, but naming the process needs
sudo(it reads/proc/<pid>/fd/). Rows you can't attribute show-for PID, user, process, and command rather than being hidden. - macOS: Other users' ports are not listed without
sudo— sockets are enumerated per process viaproc_pidfdinfo, so a process that can't be opened contributes nothing to enumerate. For the same reason doctor cannot detect TIME_WAIT pileups there; CLOSE_WAIT is detected normally. - Windows: Ports owned by inaccessible system processes are listed with the PID but
-for name and user. Kill always force-terminates. Run as Administrator for full detail. - Docker: Requires
dockerCLI and daemon access - SSH: every command falls back to agentless collection when portview is missing on the remote, using
ss+pson Linux andlsofwheressdoes not exist. The remote needs one of those and a POSIX shell. Agentless collection cannot see Docker on the far end, so that check reports as skipped rather than passed.
License
MIT