portwatch

Live terminal dashboard for monitoring your local development services.

Checks TCP ports and HTTP/HTTPS URLs on a configurable interval, shows latency, status, and when each service last changed state. Zero dependencies — uses only Node.js built-ins.

Install

npm install -g portwatch

Or without installing:

npx portwatch

Quick Start

# 1. Create a config in your project
portwatch init

# 2. Edit .portwatch.json with your services
# 3. Start the dashboard
portwatch

Example Output

portwatch  (every 5s · Ctrl+C to exit · config: .portwatch.json)

  Service           Target                  Status     Latency  Changed
  ─────────────────────────────────────────────────────────────────────────
  Frontend          localhost:3000          ✓ UP         12ms  2m ago
  Backend API       localhost:4000          ✓ UP          8ms  5m ago
  PostgreSQL        localhost:5432          ✓ UP          2ms  10m ago
  Redis             localhost:6379          ✗ DOWN          —  1m ago
  Stripe Webhook    http://localhost:8080   ✓ UP         45ms  30s ago

  Last refresh: 14:32:05

Config File (.portwatch.json)

{
  "interval": 5,
  "services": [
    { "name": "Frontend",     "target": "localhost:3000" },
    { "name": "Backend API",  "target": "localhost:4000" },
    { "name": "PostgreSQL",   "target": "localhost:5432" },
    { "name": "Redis",        "target": "localhost:6379" },
    { "name": "Health check", "target": "http://localhost:4000/health" }
  ]
}

Target formats

| Format | What it checks | |---|---| | localhost:3000 | TCP connection to port | | :5432 | TCP on localhost | | 3000 | TCP on localhost | | http://localhost:4000 | HTTP GET, checks status < 500 | | https://api.mysite.com/health | HTTPS GET |

Usage

portwatch                     # Uses .portwatch.json in current dir
portwatch init                # Create starter .portwatch.json
portwatch ./myconfig.json     # Use a specific config file

Status Indicators

| Symbol | Meaning | |---|---| | ✓ UP | Connected and responding | | ⚡ SLOW | Responding but latency > 1000ms | | ✗ DOWN | Connection refused or timed out | | checking… | Initial check in progress |

License

MIT

Keywords

port monitor · service health · dev dashboard · localhost monitor · tcp check · uptime monitor · watch ports · health dashboard · zero dependencies · cli

Built to solve, shared to help — Rushabh Shah 🛠️✨

One of 40+ zero-dependency developer CLI tools — no node_modules, ever.