PortDoc

A local dev server control panel. One binary serves a web dashboard showing what dev apps are running, which project owns each port, what URL to open, and what can be stopped safely.

• Project-grouped dashboard - services grouped by the repo that owns them, with framework labels (Next.js, Vite, Express, Redis, Postgres, and more), git branch, and package manager
• Port lookup - type a port, see exactly what owns it and act on it
• Exposure labels - know what is local-only, LAN-visible, or Docker-bound
• Stale hints - find the dev server you forgot about last week
• Safe stop - graceful stop first, with force only behind a second explicit yes
• Docker and Advanced tabs - container hints, raw sockets, JSON export

Everything runs locally. No accounts, no telemetry.

Install

Linux / macOS

curl --proto '=https' --tlsv1.2 -LsSf https://portdoc.dev/install.sh | sh

Windows (PowerShell)

irm https://portdoc.dev/install.ps1 | iex

Homebrew (macOS / Linux)

brew install bradtraversy/tap/portdoc

Binaries and checksums for every platform are on the releases page.

Use

portdoc                    # choose foreground or background in a terminal
portdoc foreground         # run attached to this terminal
portdoc ui                 # foreground alias
portdoc --port 7799        # use a different port
portdoc --no-open          # don't open the browser
portdoc --json             # print the snapshot as JSON and exit

The server binds 127.0.0.1 only; nothing is reachable from the network. Plain portdoc asks how to run only when launched in an interactive terminal. Scripts and other noninteractive launches preserve the foreground behavior without prompting. Ctrl+C stops a foreground server.

Background mode

portdoc background start             # install or refresh, then start now
portdoc background status            # show manager and health status
portdoc background stop              # stop now, keep sign-in startup enabled
portdoc background disable           # stop and remove sign-in startup
portdoc background start --port 7799 # manage a different port

Background mode uses the current user's native process manager and does not require administrator privileges:

• Linux uses a systemd user service named portdoc.service.
• macOS uses a LaunchAgent named com.traversymedia.portdoc.
• Windows uses a Task Scheduler task named PortDoc.

background start starts PortDoc immediately and enables it for future user sign-ins. It refuses to replace a foreground PortDoc or another application already using the requested port. background stop leaves sign-in startup configured, while background disable removes it.

Known limitations (v0.1)

• Background mode on Linux requires systemd. It does not enable user lingering, so PortDoc starts after sign-in rather than before it.
• Installers do not yet coordinate upgrades with an already running background instance. Stop it before upgrading, then run portdoc background start after the upgrade.
• Windows binaries are Authenticode-signed (as "Brad Traversy") since v0.1.1, so Smart App Control and SmartScreen accept them.
• macOS binaries are unsigned; the installer and Homebrew paths avoid Gatekeeper quarantine, but a manually downloaded binary may need xattr -d com.apple.quarantine.

Build from source

Needs Rust (stable, MSVC toolchain on Windows) and Node.

git clone https://github.com/bradtraversy/portdoc.git
cd portdoc/web && npm ci && npm run build   # the binary embeds web/dist
cd .. && cargo run

Development

• src/ - Rust binary: clap CLI entry, axum server, platform probes
• web/ - React + TypeScript + Vite frontend

cargo run            # server on 127.0.0.1:7788 (serves web/dist in debug too)
cargo test           # test suite
cargo clippy         # lint

cd web
npm run dev          # Vite dev server
npm run build        # production build to web/dist
npm run lint

Releases are built by cargo-dist: push a vX.Y.Z tag matching the Cargo version and CI builds binaries for Linux, macOS, and Windows, publishes them with checksums to GitHub Releases, and updates the Homebrew tap.