portview

# portview

[![CI](https://github.com/mapika/portview/actions/workflows/ci.yml/badge.svg)](https://github.com/mapika/portview/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/portview)](https://crates.io/crates/portview)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**See what's on your ports, then act on it. So can your AI agent.**

`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.

```bash
portview
```

One 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.

<p align="center">
  <img src="demo/demo.gif" alt="portview demo" width="100%" loop=infinite>
</p>

It'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.

~1 MB single binary. Zero runtime dependencies. Linux, macOS, and Windows.

## Install

```bash
curl -fsSL https://raw.githubusercontent.com/mapika/portview/main/install.sh | sh   # Linux/macOS
irm https://raw.githubusercontent.com/mapika/portview/main/install.ps1 | iex         # Windows
brew install mapika/tap/portview                                                      # Homebrew
cargo install portview                                                                # Cargo
```

Or grab a binary from [Releases](https://github.com/mapika/portview/releases).

## What it does

```bash
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        # kill what's on 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 — 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.

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`](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.

### MCP server (for AI agents)

Give 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.

```bash
claude mcp add portview -- portview mcp
```

Or configure it manually:

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

| Tool | What it does |
|------|--------------|
| `list_ports` | Every listening port with process, user, uptime, memory, full command |
| `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 |
| `find_process` | Which ports a service is on, by name or command substring |
| `doctor` | Conflicts, wildcard exposure, stale connections, resource hogs |
| `diff_ports` | What opened, closed, or changed owner since a baseline — "what did starting that actually do?" |
| `kill_port` | Terminate what's on a port (marked destructive to the client). `dry_run` shows which PIDs it would signal, without signalling them |

<p align="center">
  <img src="demo/mcp.gif" alt="portview MCP server demo" width="100%" loop=infinite>
</p>

**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.

Pass `--read-only` to withhold `kill_port` entirely, so the agent can look but not touch:

```bash
portview mcp --read-only
```

Listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as
`mcp-name: io.github.Mapika/portview`.

### Watch mode (interactive TUI)

```bash
portview watch                    # live-refresh every 1s
portview watch --docker           # Docker containers as first-class rows
portview watch --sort mem         # sort by memory on launch
```

| 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 with visual connectors. See which workers belong to which master process at a glance.

**Detail view** (`Enter`): Shows the full unwrapped command, working directory, child process list with ports, and open connections (in `--all` mode).

### Doctor

Diagnose common port problems in one command:

```
$ 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
```

| 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 |
| Stale connections | TIME_WAIT or CLOSE_WAIT pileups on one port — a connection leak |
| Resource hogs | Listeners holding more than 1 GB resident |

Docker is auto-detected. `portview doctor --json` for scripting (exit code 1 on errors).

#### In CI

There's a GitHub Action, so a workflow can fail when a service ends up exposed
or a test run leaks connections:

```yaml
- 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:

```yaml
- 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 any machine you can SSH to:

```bash
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.

**Nothing to install on the remote host.** If portview isn't there, it falls back
automatically to collecting over the same SSH connection with `ss` and `ps` —
present on essentially every Linux box:

```
$ 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 │
╰──────┴───────┴─────┴──────────────┴──────┴─────────┴────────┴───────┴──────────────────────╯
```

Force it with `--agentless` to skip the remote portview entirely. You still get
the process, user, memory, uptime, and full command — it resolves
`/proc/<pid>/exe` on the remote host, so a Node server reads as `node` rather
than the `MainThread` that `ss` reports.

`doctor` works agentless too — the checks are pure functions over collected
data, so they run locally against whatever the probe brought back:

```bash
portview ssh user@server doctor --agentless
```

That produces the same findings as running `portview doctor` on the host
itself. The Do