[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_127":128},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":21,"_24":25,"_26":27,"_28":29,"_30":31,"_32":33,"_34":25,"_35":36,"_37":-5,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":-5,"_55":47,"_56":57,"_58":59,"_60":-5,"_61":-5,"_62":-5,"_63":-5,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":-5,"_75":-5,"_76":-5,"_77":47,"_78":-5,"_79":80,"_81":82,"_83":84,"_85":86,"_87":88,"_89":90},"apiUrl","https://odel.app/api","creator","mapika","moduleId","portview","@mapika/portview","displayName","tagline","See what's on your ports, the processes behind them, and diagnose conflicts and leaks.","iconKey","https://avatars.githubusercontent.com/u/47504066?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1785558573000,"updatedAt",1788328762000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Mapika%2Fportview","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",57,"upstreamUpdatedAt",1786958444000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/Mapika/portview","githubRepoFullName","Mapika/portview","releaseId","ext-mapika-portview","version","2.1.0","descriptionMarkdown","# portview\n\n[![CI](https://github.com/mapika/portview/actions/workflows/ci.yml/badge.svg)](https://github.com/mapika/portview/actions/workflows/ci.yml)\n[![Crates.io](https://img.shields.io/crates/v/portview)](https://crates.io/crates/portview)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n**See what's on your ports, then act on it. So can your AI agent.**\n\n`lsof -i` is slow and cryptic. `ss -tlnp` is unreadable. `netstat` is deprecated. You just want to know what's on port 3000 and kill it.\n\n```bash\nportview\n```\n\nOne command. Every listening port, the process behind it, memory usage, uptime, and the full command — in a colored table. Then inspect, kill, or watch it live.\n\n

\n $\"portview$ \n

\n\nIt's also an **[MCP server](#mcp-server-for-ai-agents)** — one binary, no Node, no `npx` — so Claude Code and Cursor can answer \"what's on 3000?\" without shelling out to `lsof` and misparsing the result.\n\n~1 MB single binary. Zero runtime dependencies. Linux, macOS, and Windows.\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/mapika/portview/main/install.sh | sh # Linux/macOS\nirm https://raw.githubusercontent.com/mapika/portview/main/install.ps1 | iex # Windows\nbrew install mapika/tap/portview # Homebrew\ncargo install portview # Cargo\n```\n\nOr grab a binary from [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 # kill what's on 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 — one row per connection, so a pile-up of `TIME_WAIT` or `CLOSE_WAIT` sockets is visible rather than collapsed. `--wide` shows full commands. `--json` for scripting.\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`](https://github.com/Mapika/portview/blob/main/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\nGive your coding agent eyes on your ports. `portview mcp` speaks the [Model Context Protocol](https://modelcontextprotocol.io) over stdio, so Claude Code, Cursor, and any other MCP client can query and act on ports directly instead of shelling out to `lsof` and guessing at the output.\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` | Every listening port with process, user, uptime, memory, full command |\n| `inspect_port` | One port in detail: each process's working directory, plus its child processes — so the agent knows what else stops when it stops your dev server |\n| `find_process` | Which ports a service is on, by name or command substring |\n| `doctor` | Conflicts, wildcard exposure, stale connections, resource hogs |\n| `diff_ports` | What opened, closed, or changed owner since a baseline — \"what did starting that actually do?\" |\n| `kill_port` | Terminate what's on a port (marked destructive to the client). `dry_run` shows which PIDs it would signal, without signalling them |\n\n

\n $\"portview$ \n

\n\n**No Node, no `npx`, no runtime.** It's the same ~1 MB binary — nothing extra to install. The MCP server added 29 KB, because it pulls in no new dependencies.\n\nPass `--read-only` to withhold `kill_port` entirely, so the agent can look but not touch:\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 # Docker containers as first-class rows\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 with visual connectors. See which workers belong to which master process at a glance.\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\nDiagnose common port problems in one command:\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| Stale connections | TIME_WAIT or CLOSE_WAIT pileups on one port — a connection leak |\n| Resource hogs | Listeners holding more than 1 GB resident |\n\nDocker is auto-detected. `portview doctor --json` for scripting (exit code 1 on errors).\n\n#### In CI\n\nThere's a GitHub Action, so a workflow can fail when a service ends up exposed\nor a test run leaks connections:\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 any machine you can SSH to:\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\n**Nothing to install on the remote host.** If portview isn't there, it falls back\nautomatically to collecting over the same SSH connection with `ss` and `ps` —\npresent on essentially every Linux box:\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\nForce it with `--agentless` to skip the remote portview entirely. You still get\nthe process, user, memory, uptime, and full command — it resolves\n`/proc//exe` on the remote host, so a Node server reads as `node` rather\nthan the `MainThread` that `ss` reports.\n\n`doctor` works agentless too — the checks are pure functions over collected\ndata, so they run locally against whatever the probe brought back:\n\n```bash\nportview ssh user@server doctor --agentless\n```\n\nThat produces the same findings as running `portview doctor` on the host\nitself. The Docker check is reported as skipped rather than passed, since the\nprobe doesn't query Docker on the far end.\n\n`watch` works agentless as well, including the interactive kill:\n\n```bash\nportview ssh user@server watch --agentless\n```\n\nThe probe loops on the far end and the TUI reads the records it sends back, so\nthe whole session costs one SSH connection rather than one per refresh.\n\nAgentless mode covers everything: scans, port inspection, process search,\ndiagnostics, and watch. On Linux it uses `ss` and `ps`; where `ss` does not\nexist it falls back to `lsof`, which covers macOS and the BSDs.\n\n### Docker integration\n\nAdd `--docker` to any command. Docker-published ports appear as first-class rows:\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\nPress `d` on a Docker row to **Stop**, **Restart**, or **tail 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\nAll data is read directly from the OS — no shelling out to `lsof`, `ss`, or `netstat`.\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\nThe process name comes from the **executable**, not `/proc//comm`. `comm` is the thread name, and runtimes overwrite it — Node.js renames its main thread to `MainThread`, which is why `ps`, `ss`, and `lsof` all report a Node dev server as `MainThread`. It is also truncated to 15 bytes.\n\nDocker integration queries `docker ps` when `--docker` is passed. SSH mode runs `portview --json` on the remote host via the system `ssh` binary. MCP mode speaks newline-delimited JSON-RPC 2.0 on stdin/stdout, with a hand-rolled JSON reader — no serde, no extra dependency.\n\n## Why not...\n\n| Tool | What's missing |\n|------|---------------|\n| `lsof -i :3000` | Different flags per OS, cryptic output, slow |\n| `ss -tlnp` | Unreadable, no uptime/memory/docker, no TUI |\n| `netstat` | Deprecated on modern Linux, limited info |\n| `fkill-cli` | Requires Node.js, kill-first not diagnostic-first |\n| `procs` | General process viewer, not port-centric |\n\nNone of them speak MCP, so none of them can be handed to an agent.\n\nThere's also a smaller thing they all get wrong. Start a Node dev server and ask what's on the port:\n\n```\n$ ss -tlnp | grep 3000\nLISTEN 0 511 127.0.0.1:3000 0.0.0.0:* users:((\"MainThread\",pid=6,fd=21))\n\n$ portview 3000\nPort 3000 (TCP) — node (PID 6)\n```\n\n`ps`, `ss`, and `lsof` all read `/proc//comm`, the thread name — and Node renames its main thread to `MainThread`. portview reads the executable instead.\n\nportview is **diagnostic-first**: understand what's on your ports, then act.\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\nThere's also a `Dockerfile`. Note that a container has its own network and PID\nnamespaces, so portview inside one sees the *container's* ports — share the\nhost's namespaces to inspect the host:\n\n```bash\ndocker run --rm -i --network host --pid host portview\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](https://github.com/Mapika/portview/blob/main/CONTRIBUTING.md) for development setup and guidelines, and\n[demo/README.md](https://github.com/Mapika/portview/blob/main/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","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_108":109,"_110":111,"_112":113,"_114":115,"_116":65,"_117":118},"requiredSecrets",[],"tags",[93,94,95,96,97,98,99,100,101,102,103,104,105,106,107],"assets",[],"stats",{"_91":80,"_92":80},"ratingAvg","reviewCount","ai-agents","cli","devops","devtools","diagnostics","docker","linux","macos","network","port","process","rust","ssh","sysadmin","terminal","topics",[93,94,95,96,97,98,99,100,123,124,101,102,103,104,105,106,107,125,126],"license","MIT","language","Rust","registryName","io.github.Mapika/portview","homepage","packages",[119],{"_120":121,"_122":21,"_70":71},"registryType","cargo","identifier","mcp","mcp-server","tui","windows","ENV",{"_129":130,"_131":132,"_133":134},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]