porthole

module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 14, 2026 License: MIT

README

porthole

A port kill switch and service viewer for your terminal.

See what's listening on your machine, know which project owns it, and kill it in one keystroke — from an animated TUI or a scriptable CLI, backed by the same engine. Cross-platform: Linux, macOS, Windows.

CI Go Reference Go Report Card Latest release


Why porthole

lsof -i :3000 | grep LISTEN and kill -9 $(lsof -t -i:3000) work, but they don't answer the question you actually have:

  • "Which of my projects owns this port?" node on port 3000 is useless information. zapmail-web on port 3000 is the answer. Porthole walks up from the listening process's working directory to find the nearest package.json/go.mod/Cargo.toml/.git and shows you the project name, not just the process name.
  • "Is it safe to kill?" Porthole verifies the process is still the one it scanned — by PID and start time — immediately before signaling it, so a recycled PID never gets the wrong process killed.
  • "What actually happens when I hit kill?" SIGTERM, wait, escalate to SIGKILL only if it's ignored — the same ladder every time, whether you're in the TUI, the CLI, the daemon, or the web dashboard.
┌─ porthole ──────────────────────────────────────────────────────┐
│ PORT   PID    PROCESS   PROJECT       CONTAINER   UPTIME         │
│ 3000   48211  node      zapmail-web   -           2h 14m         │
│ 5432   1092   postgres  -             pg-dev       6d            │
│ 6379   2288   redis     -             -            18m           │
└────────────────────────────────────────────────────────────────┘
  ↑↓ nav · space select · k kill · K force · / filter · w watch · ? help

Install

# Homebrew (macOS + Linux)
brew install subh05sus/tap/porthole

# Scoop (Windows)
scoop bucket add porthole https://github.com/subh05sus/scoop-bucket
scoop install porthole

# curl | bash (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/subh05sus/porthole/main/install.sh | bash

# go install (any platform with Go)
go install github.com/subh05sus/porthole/cmd/porthole@latest

Prebuilt binaries for Linux/macOS/Windows × amd64/arm64 are on the releases page.

Quick start

porthole                 # launch the interactive TUI
porthole list             # table to stdout
porthole list --json      # for scripts/jq
porthole kill 3000        # SIGTERM, escalate after 2s if ignored
porthole kill 3000 8080   # multiple ports at once
porthole watch             # headless live tail, no TUI

Commands

Command What it does
porthole Launch the interactive TUI
porthole list [--json|--oneline] [--port N] [--project NAME] [--since 5m] [--containers] [--all] List listening services
porthole kill <ports...> [--force] [--dry-run] [--yes] [--project NAME] [--dev] Kill whatever's listening on one or more ports
porthole watch [--interval 2s] [--notify] [--all] Headless live tail — prints what changed, no TUI
porthole restart <port> Kill a process, then respawn it with the same command/cwd/env
porthole doctor Diagnose common permission/environment issues
porthole history Show recent kills (who, when, what happened)
porthole serve [--port 9191] Local-only web dashboard (binds 127.0.0.1, never the network)
porthole firewall block|allow <port> [--proto tcp|udp] [--out] Add an isolated firewall rule for a port porthole discovered
porthole firewall list / porthole firewall clean List / remove porthole-owned firewall rules
porthole daemon [--live] [--interval 5s] Auto-kill daemon — see Auto-kill daemon below

Every command supports --help for the full flag list.

TUI keybindings

Key Action
↑ ↓ / j Navigate
enter Detail pane (full cmdline, cwd, env, sockets, CPU%/RSS)
space Multi-select
k Kill (graceful)
K Force kill
R Restart
/ Filter by port, process, or project
a Toggle showing rows hidden by display.hide_*
w Toggle watch mode
r Refresh
? Help
q / esc Quit

Configuration

Optional ~/.porthole.yaml — porthole works fine with no config file at all.

protected:
  - 5432
  - port: 3306
    reason: "prod tunnel, do not touch"

theme: auto                # "auto" | "color" | "plain"
animations: true           # staggered reveal, fade-out on kill, spinner

display:
  hide_system_processes: false   # hide rows you don't own (can't kill anyway)
  hide_privileged_ports: false   # hide ports < 1024, regardless of ownership

kill:
  dev_port_range: "3000-9999"    # the range --dev sweeps
  escalation_timeout: 2s         # how long to wait after SIGTERM before SIGKILL is eligible

watch:
  interval: 2s

auto_kill:
  enabled: false          # opt-in, see below
  interval: 5s
  allow:
    - port: 3000
      process: node

Protected ports need a typed confirmation (the exact port number) instead of a plain y/n — and --yes does not bypass it, in either the CLI or the TUI.

Display filters (hide_system_processes/hide_privileged_ports) only affect what's shown in list/watch/the TUI — they never change what porthole kill <port> can target, and --all (CLI) or a (TUI) shows everything for one run/session regardless of config. Both are relative to the current invocation's privilege level: running elevated reveals more rows, not fewer, since more of them become yours.

Auto-kill daemon (opt-in)

porthole daemon watches for services matching an exact (port, process-name) allow-list and kills them automatically. This is the most dangerous thing porthole can do, so it's built with rails on every side:

  • Disabled by default — auto_kill.enabled: true is required even with allow entries present.
  • Dry-run by default, even when enabled — real kills need the explicit --live flag, every time you start it. There's no config-file toggle for that, and nothing reachable from the TUI.
  • Exact matches only — no wildcards, ranges, or patterns.
  • Re-verified immediately before every kill against a fresh scan, not just trusted from when it first matched.
  • Rate-limited — a cooldown per port so a crash-looping process can't be killed in a tight loop.
  • Every kill goes through the exact same PID-reuse-guarded kill ladder as everything else in porthole.
porthole daemon                 # dry-run: logs what it would kill
porthole daemon --live          # actually kills matches
Firewall rules

porthole firewall manages a small set of OS firewall rules scoped to exactly what porthole already showed you — one port, one protocol at a time, never a CIDR or a wildcard. Every rule lives in an isolated group porthole exclusively owns (a dedicated netsh rule name prefix on Windows, a dedicated PORTHOLE chain on Linux iptables, a dedicated pf anchor on macOS) and porthole never touches anything it didn't create itself. There's no --yes flag anywhere in this command tree — every change requires typing the exact port number to confirm.

How it works

  • Kill ladder: verify the target is still the process that was scanned (PID + start time) → SIGTERM → wait → SIGKILL only if still alive. The same ladder runs behind the CLI, the TUI, the web dashboard, and the daemon — one code path, everywhere.
  • Project detection: walks up from the process's working directory looking for package.json, go.mod, Cargo.toml, pyproject.toml, or .git, with the result cached per-session and persisted across runs.
  • Container awareness: cross-references listening ports against the Docker Engine API's published-port list, so a container-forwarded port shows the real container name/image, and killing it routes to docker stop instead of signaling the host-side proxy process.
  • Cross-platform by construction: every OS-specific piece (socket scanning, process metadata, signaling) sits behind a small interface, with the OS-agnostic logic (the kill ladder, project detection, config, filtering) fully portable and unit-tested independent of any real OS.

Building from source

git clone https://github.com/subh05sus/porthole.git
cd porthole
go build -o porthole ./cmd/porthole
go test ./...

Requires Go 1.26+. No cgo, no external dependencies beyond the Go module graph — porthole ships as a single static binary.

More docs

  • EXAMPLES.md — real-world recipes: scripting --json, status-bar integration, the auto-kill daemon and firewall rules walked through end to end, container debugging
  • ARCHITECTURE.md — how porthole is built: the kill ladder's algorithm, the portable/OS-glue split, the TUI's concurrency model
  • FAQ.md — safety/permissions questions, how porthole compares to lsof/fkill-cli/npx kill-port
  • ROADMAP.md — what's shipped, what's not verified yet, what's next
  • CHANGELOG.md — release history

Support the project

Porthole is free and open source, and that isn't going to change. If it's saved you time, or you'd like to help fund the work, you can back it directly:

Sponsor on GitHub Sponsors Buy me a coffee Support via Wise PayPal

Can't chip in right now? A star, a share, or a solid bug report counts for just as much. Thank you.

Contributing

Bug reports, feature requests, and PRs are welcome — see CONTRIBUTING.md and SUPPORT.md.

Security

Porthole kills processes, manages firewall rules, and can auto-kill things unsupervised — if you find a security issue, please report it responsibly. See SECURITY.md.

License

MIT

Directories

Path Synopsis
cmd
porthole command
Command porthole is a port kill switch and service viewer for your terminal.
Command porthole is a port kill switch and service viewer for your terminal.
internal
cli
Package cli implements the porthole command tree.
Package cli implements the porthole command tree.
config
Package config loads porthole's optional ~/.porthole.yaml — protected ports (FUTURE_PLANS.md v1.3) plus a few display/behavior settings.
Package config loads porthole's optional ~/.porthole.yaml — protected ports (FUTURE_PLANS.md v1.3) plus a few display/behavior settings.
container
Package container talks to a local Docker-Engine-API-compatible daemon (Docker, Podman, OrbStack, Colima) to enrich scan results with container names/images and route kills through `docker stop` instead of signaling the docker-proxy PID directly.
Package container talks to a local Docker-Engine-API-compatible daemon (Docker, Podman, OrbStack, Colima) to enrich scan results with container names/images and route kills through `docker stop` instead of signaling the docker-proxy PID directly.
daemon
Package daemon implements `porthole daemon` — an auto-kill daemon that watches for services matching a user-authored allow-list and kills them.
Package daemon implements `porthole daemon` — an auto-kill daemon that watches for services matching a user-authored allow-list and kills them.
firewall
Package firewall manages a small, isolated set of firewall rules scoped to exactly what porthole already discovered in a scan — never arbitrary rules, CIDRs, or ports the user didn't already see.
Package firewall manages a small, isolated set of firewall rules scoped to exactly what porthole already discovered in a scan — never arbitrary rules, CIDRs, or ports the user didn't already see.
firewall/firewallfmt
Package firewallfmt parses `netsh advfirewall firewall show rule` output.
Package firewallfmt parses `netsh advfirewall firewall show rule` output.
firewall/firewalltest
Package firewalltest provides a scriptable firewall.Manager test double, mirroring scan/scantest, kill/killtest, and proc/proctest.
Package firewalltest provides a scriptable firewall.Manager test double, mirroring scan/scantest, kill/killtest, and proc/proctest.
history
Package history implements FUTURE_PLANS.md's "history" idea: a JSONL log of what porthole killed and when, so "wait, did I kill that" has an answer.
Package history implements FUTURE_PLANS.md's "history" idea: a JSONL log of what porthole killed and when, so "wait, did I kill that" has an answer.
kill
Package kill implements the OS-agnostic kill ladder: verify the target is still the process we scanned, signal it, wait, and escalate.
Package kill implements the OS-agnostic kill ladder: verify the target is still the process we scanned, signal it, wait, and escalate.
kill/killtest
Package killtest provides a scriptable kill.Killer test double so CLI and TUI code can be tested without a real operating system.
Package killtest provides a scriptable kill.Killer test double so CLI and TUI code can be tested without a real operating system.
notify
Package notify sends best-effort desktop notifications for watch mode's --notify flag, by shelling out to whatever native notifier tool the OS already ships rather than adding a notification library dependency.
Package notify sends best-effort desktop notifications for watch mode's --notify flag, by shelling out to whatever native notifier tool the OS already ships rather than adding a notification library dependency.
output
Package output renders []scan.Service for the CLI: a plain table for humans and JSON for scripts.
Package output renders []scan.Service for the CLI: a plain table for humans and JSON for scripts.
portrange
Package portrange parses a single port-or-range token, shared between internal/cli's --dev/kill-args handling and internal/config's validation of kill.dev_port_range — a leaf package so internal/config (which cli already imports) never needs to import internal/cli.
Package portrange parses a single port-or-range token, shared between internal/cli's --dev/kill-args handling and internal/config's validation of kill.dev_port_range — a leaf package so internal/config (which cli already imports) never needs to import internal/cli.
proc
Package proc resolves per-process metadata (name, cmdline, cwd, user, start time) for a PID discovered by internal/scan.
Package proc resolves per-process metadata (name, cmdline, cwd, user, start time) for a PID discovered by internal/scan.
proc/proctest
Package proctest provides a scriptable proc.Lookup test double, mirroring scan/scantest and kill/killtest.
Package proctest provides a scriptable proc.Lookup test double, mirroring scan/scantest and kill/killtest.
project
Package project resolves a project name from a process's working directory — the thing PRD.md calls out as porthole's actual differentiator: "node on port 3000" is useless, "zapmail-web on port 3000" is the answer you wanted.
Package project resolves a project name from a process's working directory — the thing PRD.md calls out as porthole's actual differentiator: "node on port 3000" is useless, "zapmail-web on port 3000" is the answer you wanted.
restart
Package restart implements PRD's v1.2 feature (FUTURE_PLANS.md): kill a process and immediately respawn it with the same command line, working directory, and environment.
Package restart implements PRD's v1.2 feature (FUTURE_PLANS.md): kill a process and immediately respawn it with the same command line, working directory, and environment.
restart/restarttest
Package restarttest provides a scriptable restart.Spawner test double, mirroring scan/scantest and kill/killtest — necessary because the real Spawner actually launches a new OS process.
Package restarttest provides a scriptable restart.Spawner test double, mirroring scan/scantest and kill/killtest — necessary because the real Spawner actually launches a new OS process.
scan
Package scan discovers listening network sockets and the processes behind them.
Package scan discovers listening network sockets and the processes behind them.
scan/lsoffmt
Package lsoffmt parses macOS lsof/ps text formats.
Package lsoffmt parses macOS lsof/ps text formats.
scan/procfmt
Package procfmt parses Linux /proc text formats.
Package procfmt parses Linux /proc text formats.
scan/scantest
Package scantest provides a scriptable scan.Lister test double so that every layer above the OS boundary (CLI, TUI, watch engine) can be tested without a real operating system.
Package scantest provides a scriptable scan.Lister test double so that every layer above the OS boundary (CLI, TUI, watch engine) can be tested without a real operating system.
tui
Package tui implements porthole's interactive Bubble Tea interface.
Package tui implements porthole's interactive Bubble Tea interface.
tui/anim
Package anim holds pure animation math for the TUI: no bubbletea dependency, no wall-clock reads of its own — every function takes elapsed time as a parameter, so it's fully deterministic and testable.
Package anim holds pure animation math for the TUI: no bubbletea dependency, no wall-clock reads of its own — every function takes elapsed time as a parameter, so it's fully deterministic and testable.
tui/theme
Package theme centralizes every lipgloss style the TUI uses, resolved once at startup so the rest of the TUI never has to think about color degradation itself.
Package theme centralizes every lipgloss style the TUI uses, resolved once at startup so the rest of the TUI never has to think about color degradation itself.
webui
Package webui implements `porthole serve`'s optional local web dashboard: a small stdlib net/http server exposing the scan/kill loop as a JSON API plus one embedded HTML/JS page.
Package webui implements `porthole serve`'s optional local web dashboard: a small stdlib net/http server exposing the scan/kill loop as a JSON API plus one embedded HTML/JS page.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL