{
"markdown": "# portview\n\n[](https://github.com/mapika/portview/actions/workflows/ci.yml)\n[](https://crates.io/crates/portview)\n[](LICENSE)\n\nportview lists ports and the processes using them on Linux, macOS, and Windows.\nIt shows process names, commands, memory usage, and uptime. You can inspect a\nport, stop its process, or monitor changes in an interactive terminal UI.\n\n
\n \n
\n\nIt also supports [Docker](#docker-integration), [remote hosts over SSH](#ssh-remote-mode),\nand an [MCP server](#mcp-server-for-ai-agents) for coding agents.\n\n## Install\n\nHomebrew:\n\n```bash\nbrew install mapika/tap/portview\n```\n\nLinux / macOS:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/mapika/portview/main/install.sh | sh\n```\n\nWindows (PowerShell):\n\n```powershell\nirm https://raw.githubusercontent.com/mapika/portview/main/install.ps1 | iex\n```\n\nOr use `cargo install portview`, or download a binary from\n[Releases](https://github.com/mapika/portview/releases).\n\n## What it does\n\n```bash\nportview # list all listening ports\nportview 3000 # inspect port 3000 in detail\nportview node # find ports by process name\nportview watch # interactive TUI with live refresh\nportview watch --docker # TUI with Docker containers as rows\nportview kill 3000 --force # terminate the process using port 3000\nportview doctor # diagnose port conflicts and issues\nportview ssh user@server # inspect ports on a remote host\nportview ssh user@server watch # remote TUI over SSH\nportview ssh user@server --agentless # no portview needed on the remote\nportview mcp # run as an MCP server for AI agents\n```\n\n## Features\n\n### Scan\n\n```\n$ portview\n╭──────┬───────┬─────┬──────────────┬──────┬────────────┬────────┬────────┬────────────────────────────╮\n│ PORT │ PROTO │ PID │ ADDR │ USER │ PROCESS │ UPTIME │ MEM │ COMMAND │\n├──────┼───────┼─────┼──────────────┼──────┼────────────┼────────┼────────┼────────────────────────────┤\n│ 3000 │ TCP │ 8 │ 127.0.0.1 │ root │ node │ 7s │ 44 MB │ node /opt/app/web.js │\n│ 5000 │ TCP │ 11 │ 127.0.0.1 │ root │ python3.12 │ 7s │ 18 MB │ python3 /opt/app/worker.py │\n│ 6380 │ TCP │ 12 │ 127.0.0.1 │ root │ node │ 7s │ 1.2 GB │ node /opt/app/cache.js │\n│ 7000 │ TCP │ 10 │ 127.0.0.1 │ root │ node │ 7s │ 45 MB │ node /opt/app/ingest.js │\n│ 8080 │ TCP │ 9 │ 127.0.0.1 │ root │ node │ 7s │ 44 MB │ node /opt/app/api.js │\n╰──────┴───────┴─────┴──────────────┴──────┴────────────┴────────┴────────┴────────────────────────────╯\n```\n\n`--all` includes non-listening connections, with one row per connection.\n`--wide` shows full commands. `--json` produces JSON output for scripts.\n\nPorts 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.\n\n> The scan, doctor, and MCP examples below are real output, captured by [`demo/record.sh`](demo/README.md) 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.\n\n### MCP server (for AI agents)\n\n`portview mcp` provides port queries, diagnostics, and process termination over\nthe [Model Context Protocol](https://modelcontextprotocol.io) using stdio.\nTo register it with Claude Code:\n\n```bash\nclaude mcp add portview -- portview mcp\n```\n\nOr configure it manually:\n\n```json\n{\n \"mcpServers\": {\n \"portview\": {\n \"command\": \"portview\",\n \"args\": [\"mcp\"]\n }\n }\n}\n```\n\n| Tool | What it does |\n|------|--------------|\n| `list_ports` | List listening ports with available process details |\n| `inspect_port` | Inspect a port, including process working directories and descendants |\n| `find_process` | Find ports by process name or command substring |\n| `doctor` | Check for conflicts, wildcard exposure, connection buildup, and high memory usage |\n| `diff_ports` | Report ports that opened, closed, or changed owner since a baseline |\n| `kill_port` | Terminate processes using a port; `dry_run` previews the targets. Marked destructive to the client |\n\n
\n \n
\n\nThe MCP server is included in the portview binary. Pass `--read-only` to disable\nthe `kill_port` tool:\n\n```bash\nportview mcp --read-only\n```\n\nListed in the [MCP Registry](https://registry.modelcontextprotocol.io) as\n`mcp-name: io.github.Mapika/portview`.\n\n### Watch mode (interactive TUI)\n\n```bash\nportview watch # live-refresh every 1s\nportview watch --docker # include Docker containers\nportview watch --sort mem # sort by memory on launch\n```\n\n| Key | Action |\n|-----|--------|\n| `j`/`k`, `↑`/`↓` | Navigate rows |\n| `Enter` | Inspect port (full command, cwd, children, connections) |\n| `d`/`D` | Kill process or manage Docker container |\n| `/` | Filter across all columns |\n| `←`/`→`, `r` | Cycle sort column, reverse direction |\n| `t` | Toggle process tree view |\n| `a` | Toggle all/listening-only |\n| `q` | Quit |\n\n**Tree view** (`t`): Groups child processes under their parents.\n\n**Detail view** (`Enter`): Shows the full unwrapped command, working directory, child process list with ports, and open connections (in `--all` mode).\n\n### Doctor\n\n`portview doctor` checks for port conflicts, wildcard bindings, connection\nbuildup, and high memory usage:\n\n```\n$ portview doctor\n ✓ No port conflicts\n ✓ No wildcard exposure issues\n ! Port 7000 has 16 CLOSE_WAIT connections — possible connection leak\n ! node (PID 12) is listening on port 6380 and using 1.2 GB of memory\n\n 2 warnings found\n```\n\n| Check | Flags |\n|-------|-------|\n| Port conflicts | Multiple PIDs bound to the same port |\n| Wildcard exposure | Databases (postgres, redis, mysql, mongod, …) listening on `0.0.0.0` |\n| Docker-host conflicts | A container publishing a port the host already uses |\n| Connection buildup | High counts of TIME_WAIT or CLOSE_WAIT connections on one port; these do not by themselves establish a leak |\n| High memory usage | Listening processes using more than 1 GB of resident memory |\n\nDocker is auto-detected. `portview doctor --json` for scripting (exit code 1 on errors).\n\n#### In CI\n\nThe GitHub Action runs `doctor` and can fail a workflow on errors or warnings:\n\n```yaml\n- uses: mapika/portview@v2\n with:\n fail-on: error # error | warning | never\n```\n\nIt annotates each finding inline on the run, writes a summary table, and exposes\n`findings` (JSON), `count`, `errors`, and `warnings` as step outputs:\n\n```yaml\n- uses: mapika/portview@v2\n id: doctor\n with:\n fail-on: never\n- run: echo '${{ steps.doctor.outputs.findings }}' | jq .\n```\n\nSet `install: false` if portview is already on PATH. Linux and macOS runners.\n\n### SSH remote mode\n\nInspect ports on a remote host over SSH:\n\n```bash\nportview ssh user@server # one-shot scan\nportview ssh user@server watch # full interactive TUI\nportview ssh user@server doctor # remote diagnostics\nportview ssh user@server 3000 # inspect a remote port\nportview ssh user@server --ssh-opt \"-p 2222\" # custom SSH port\n```\n\nKill actions in the remote TUI are forwarded over SSH.\n\nIf portview is not installed on the remote host, SSH mode collects data using\n`ss` and `ps`, or `lsof` and `ps` where `ss` is unavailable. This requires a\nPOSIX shell and the collection tools on the remote host.\n\n```\n$ portview ssh user@server\nportview not found on user@server — falling back to agentless mode (ss + ps over SSH).\n╭──────┬───────┬─────┬──────────────┬──────┬─────────┬────────┬───────┬──────────────────────╮\n│ PORT │ PROTO │ PID │ ADDR │ USER │ PROCESS │ UPTIME │ MEM │ COMMAND │\n├──────┼───────┼─────┼──────────────┼──────┼─────────┼────────┼───────┼──────────────────────┤\n│ 3000 │ TCP │ 6 │ 127.0.0.1 │ root │ node │ 3s │ 45 MB │ node /opt/app/web.js │\n│ 8080 │ TCP │ 7 │ 127.0.0.1 │ root │ node │ 3s │ 45 MB │ node /opt/app/api.js │\n╰──────┴───────┴─────┴──────────────┴──────┴─────────┴────────┴───────┴──────────────────────╯\n```\n\nUse `--agentless` to collect data this way even when portview is installed on\nthe remote host. It supports scans, port inspection, process search,\ndiagnostics, and watch mode.\n\nRun diagnostics on the collected data:\n\n```bash\nportview ssh user@server doctor --agentless\n```\n\nThis uses the same diagnostic checks as local mode. The Docker check is\nskipped because agentless mode does not query remote containers.\n\nWatch remote ports, with process termination available in the TUI:\n\n```bash\nportview ssh user@server watch --agentless\n```\n\nWatch mode collects updates through a single persistent SSH connection.\n\n### Docker integration\n\nUse `--docker` to include ports published by Docker containers:\n\n```\n$ portview --docker\n╭──────┬───────┬───────┬──────────────┬────────┬──────────┬────────┬────────┬────────────────────────────╮\n│ PORT │ PROTO │ PID │ ADDR │ USER │ PROCESS │ UPTIME │ MEM │ COMMAND │\n├──────┼───────┼───────┼──────────────┼────────┼──────────┼────────┼────────┼────────────────────────────┤\n│ 3000 │ TCP │ 48291 │ 127.0.0.1 │ mark │ node │ 3h 12m │ 248 MB │ next dev [docker:web] │\n│ 8080 │ TCP │ - │ 0.0.0.0 │ docker │ pv-nginx │ - │ - │ nginx:alpine :8080->80/tcp │\n╰──────┴───────┴───────┴──────────────┴────────┴──────────┴────────┴────────┴────────────────────────────╯\n```\n\nContainer-only rows have no host process, so `PID`, `UPTIME`, and `MEM` render as `-`.\n\nIn watch mode, press `d` on a Docker row to stop or restart the container, or\nfollow its logs.\n\n### JSON output\n\n```bash\nportview --json # pipe to jq, scripts, dashboards\nportview --docker --json # includes Docker ownership data\nportview watch --json # streaming JSON, one array per tick\nportview doctor --json # machine-readable diagnostics\n```\n\n### Custom colors\n\n```bash\nPORTVIEW_COLORS=\"port=red,pid=magenta,command=bright_cyan\" portview\n```\n\nColumns: `port`, `proto`, `pid`, `user`, `process`, `uptime`, `mem`, `command`. Use `--no-color` to disable.\n\n## How it works\n\nLocal port and process data comes from OS interfaces:\n\n| Field | Linux | macOS | Windows |\n|-------|-------|-------|---------|\n| Ports | `/proc/net/tcp{,6}`, `udp{,6}` | `proc_pidfdinfo` | `GetExtendedTcp/UdpTable` |\n| PID | inode→pid via `/proc/*/fd/` | `proc_listpids` | Included in socket table |\n| Process | `/proc//exe` | `proc_pidpath` | `QueryFullProcessImageNameW` |\n| Memory | `/proc//status` VmRSS | `proc_pidinfo` | `K32GetProcessMemoryInfo` |\n| Uptime | `/proc//stat` | `proc_pidinfo` | `GetProcessTimes` |\n\nOn Linux, portview reads the executable name from `/proc//exe`.\nThe thread name in `/proc//comm` can be changed by the runtime and is\nlimited to 15 bytes.\n\nDocker integration uses the `docker` CLI. SSH mode uses the system `ssh`\nclient to run portview or the agentless collection tools on the remote host.\nMCP mode uses newline-delimited JSON-RPC 2.0 on stdin/stdout.\n\n## Building from source\n\n```bash\ngit clone https://github.com/mapika/portview\ncd portview\ncargo build --release\n```\n\nRequires Rust 1.85+ (edition 2024). Shell completions and man page are generated at build time.\n\nThe repository includes a `Dockerfile`. To inspect the host from a container,\nshare the host's network and PID namespaces:\n\n```bash\ndocker run --rm -i --network host --pid host portview\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines, and\n[demo/README.md](demo/README.md) for regenerating the recordings.\n\nChanges should type-check on all three platforms, not just yours:\n\n```bash\ncargo check --target aarch64-apple-darwin\ncargo check --target x86_64-pc-windows-msvc\n```\n\n## Limitations\n\n- **Linux:** Other users' ports are listed, but naming the process needs `sudo` (it reads `/proc//fd/`). Rows you can't attribute show `-` for PID, user, process, and command rather than being hidden.\n- **macOS:** Other users' ports are *not* listed without `sudo` — sockets are enumerated per process via `proc_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.\n- **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.\n- **Docker:** Requires `docker` CLI and daemon access\n- **SSH:** every command falls back to agentless collection when portview is missing on the remote, using `ss` + `ps` on Linux and `lsof` where `ss` does 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.\n\n## License\n\nMIT\n",
"bytes": 13474,
"sha": "0e410e7b98aea2d5990b7d0727cddb3a19da06d188d614ed76cdecd5daf3243a",
"repo_slug": "mapika/portview",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_mapika_portview_646ed79a/readme"
}
![\"portview](\"demo/demo.gif\")
\n![\"portview](\"demo/mcp.gif\")
\n