portview

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:

brew install mapika/tap/portview

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/mapika/portview/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/mapika/portview/main/install.ps1 | iex

Or use cargo install portview, or download a binary from Releases.

What it does

portview                          # list all listening ports

portview 3000 # inspect port 3000 in detail portview node # find ports by process name portview watch # interactive TUI with live refresh portview watch --docker # TUI with Docker containers as rows portview kill 3000 --force # terminate the process using port 3000 portview doctor # diagnose port conflicts and issues portview ssh user@server # inspect ports on a remote host portview ssh user@server watch # remote TUI over SSH portview ssh user@server --agentless # no portview needed on the remote portview mcp # run as an MCP server for AI agents

Features

Scan

$ portview

╭──────┬───────┬─────┬──────────────┬──────┬────────────┬────────┬────────┬────────────────────────────╮ │ PORT │ PROTO │ PID │ ADDR │ USER │ PROCESS │ UPTIME │ MEM │ COMMAND │ ├──────┼───────┼─────┼──────────────┼──────┼────────────┼────────┼────────┼────────────────────────────┤ │ 3000 │ TCP │ 8 │ 127.0.0.1 │ root │ node │ 7s │ 44 MB │ node /opt/app/web.js │ │ 5000 │ TCP │ 11 │ 127.0.0.1 │ root │ python3.12 │ 7s │ 18 MB │ python3 /opt/app/worker.py │ │ 6380 │ TCP │ 12 │ 127.0.0.1 │ root │ node │ 7s │ 1.2 GB │ node /opt/app/cache.js │ │ 7000 │ TCP │ 10 │ 127.0.0.1 │ root │ node │ 7s │ 45 MB │ node /opt/app/ingest.js │ │ 8080 │ TCP │ 9 │ 127.0.0.1 │ root │ node │ 7s │ 44 MB │ node /opt/app/api.js │ ╰──────┴───────┴─────┴──────────────┴──────┴────────────┴────────┴────────┴────────────────────────────╯

--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.sh inside an isolated namespace — which is why the user is root and 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:

claude mcp add portview -- portview mcp

Or configure it manually:

{

"mcpServers": { "portview": { "command": "portview", "args": ["mcp"] } } }

The MCP server is included in the portview binary. Pass --read-only to disable the kill_port tool:

portview mcp --read-only

Listed in the MCP Registry as mcp-name: io.github.Mapika/portview.

Watch mode (interactive TUI)

portview watch                    # live-refresh every 1s

portview watch --docker # include Docker containers portview watch --sort mem # sort by memory on launch

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:

$ portview doctor

✓ No port conflicts ✓ No wildcard exposure issues ! Port 7000 has 16 CLOSE_WAIT connections — possible connection leak ! node (PID 12) is listening on port 6380 and using 1.2 GB of memory

2 warnings found

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:

- uses: mapika/portview@v2

with: fail-on: error # error | warning | never

It annotates each finding inline on the run, writes a summary table, and exposes findings (JSON), count, errors, and warnings as step outputs:

- uses: mapika/portview@v2

id: doctor with: fail-on: never

• run: echo '${{ steps.doctor.outputs.findings }}' | jq .

Set install: false if portview is already on PATH. Linux and macOS runners.

SSH remote mode

Inspect ports on a remote host over SSH:

portview ssh user@server              # one-shot scan

portview ssh user@server watch # full interactive TUI portview ssh user@server doctor # remote diagnostics portview ssh user@server 3000 # inspect a remote port portview ssh user@server --ssh-opt "-p 2222" # custom SSH port

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.

$ portview ssh user@server

portview not found on user@server — falling back to agentless mode (ss + ps over SSH). ╭──────┬───────┬─────┬──────────────┬──────┬─────────┬────────┬───────┬──────────────────────╮ │ PORT │ PROTO │ PID │ ADDR │ USER │ PROCESS │ UPTIME │ MEM │ COMMAND │ ├──────┼───────┼─────┼──────────────┼──────┼─────────┼────────┼───────┼──────────────────────┤ │ 3000 │ TCP │ 6 │ 127.0.0.1 │ root │ node │ 3s │ 45 MB │ node /opt/app/web.js │ │ 8080 │ TCP │ 7 │ 127.0.0.1 │ root │ node │ 3s │ 45 MB │ node /opt/app/api.js │ ╰──────┴───────┴─────┴──────────────┴──────┴─────────┴────────┴───────┴──────────────────────╯

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:

portview ssh user@server doctor --agentless

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:

portview ssh user@server watch --agentless

Watch mode collects updates through a single persistent SSH connection.

Docker integration

Use --docker to include ports published by Docker containers:

$ portview --docker

╭──────┬───────┬───────┬──────────────┬────────┬──────────┬────────┬────────┬────────────────────────────╮ │ PORT │ PROTO │ PID │ ADDR │ USER │ PROCESS │ UPTIME │ MEM │ COMMAND │ ├──────┼───────┼───────┼──────────────┼────────┼──────────┼────────┼────────┼────────────────────────────┤ │ 3000 │ TCP │ 48291 │ 127.0.0.1 │ mark │ node │ 3h 12m │ 248 MB │ next dev [docker:web] │ │ 8080 │ TCP │ - │ 0.0.0.0 │ docker │ pv-nginx │ - │ - │ nginx:alpine :8080->80/tcp │ ╰──────┴───────┴───────┴──────────────┴────────┴──────────┴────────┴────────┴────────────────────────────╯

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

portview --json                   # pipe to jq, scripts, dashboards

portview --docker --json # includes Docker ownership data portview watch --json # streaming JSON, one array per tick portview doctor --json # machine-readable diagnostics

Custom colors

PORTVIEW_COLORS="port=red,pid=magenta,command=bright_cyan" portview

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:

On Linux, portview reads the executable name from /proc/ /exe. The thread name in /proc/ /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

git clone https://github.com/mapika/portview

cd portview cargo build --release

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: