wiremonitor

Network traffic web dashboard. Reads a local SQLite database produced by wirewatch and displays live connections, AI analyses, and session statistics in a browser. No cloud, no telemetry.

wiremonitor serves a local HTTP dashboard and streams new connections to the browser in real time via Server-Sent Events. It reads the database in read-only mode — it never writes, never interferes with the capture daemon.

What It Does

• serves a local web dashboard at http://localhost:PORT
• streams live connections via Server-Sent Events as new records arrive
• displays connection table with filtering by protocol, direction, process, country, and destination IP
• shows connection detail on click with full metadata
• lists AI analyses with risk level, summary, and flagged connections grouped by process and destination
• identifies known processes by name (VS Code, Chrome, Slack, node, etc.)
• displays database and session statistics with visual breakdowns including top processes and top countries
• shows daemon status (running / stopped) updated live
• live SSE status pill shows whether the browser stream is connected
• dark and light theme toggle, persisted across sessions
• opens the browser automatically on start

Requirements

• Node.js 22+
• A local SQLite database produced by wirewatch or a compatible capture daemon

For development or building from source:

• pnpm 10.33.0+

Install

npm install -g wiremonitor

Verify the installation:

wm --help

The wm command is now available globally.

From source

git clone https://github.com/psandis/wiremonitor.git
cd wiremonitor
pnpm install
pnpm build
npm link

Verify:

wm --help

The wm command is now available globally.

Quick Start

Start the dashboard:

wm --db ~/.wirewatch/wirewatch.db

wiremonitor running at http://localhost:3311

Opens in your default browser. Updates automatically as new connections arrive. Stop with Ctrl+C.

Dashboard

Header

A fixed header shows:

• WM logo — brand mark on the left
• Status pill — green and pulsing when the capture daemon is running, red when stopped, polled every 5 seconds
• Live pill — shows the state of the SSE stream: connecting, connected (green pulse), or offline (red). Flashes briefly on each new event received
• Theme toggle — switches between dark and light mode, persisted to localStorage
• Navigation — Connections / Analyses / Stats

Connections

A live table of captured connections, newest first.

Column	Description
ID	Connection ID
Proto	TCP or UDP
Source	Source IP and port
Destination	Destination hostname or IP and port
Dir	Direction: outbound / inbound / local
State	Connection state (ESTABLISHED, TIME_WAIT, etc.)
Process	Process name that opened the connection
CC	Country code of the destination
Last Seen	Timestamp of last activity

Filter bar above the table:

Filter	Description
Protocol	TCP or UDP
Direction	outbound / inbound / local
Process	Exact match on process name
Country	Two-letter country code
IP chip	Active when clicking a destination in Analyses — shows destination IP and clears on ✕

Direction is shown as an arrow badge: → outbound, ← inbound, ⇄ local.

New rows animate in at the top as the SSE stream delivers them. Clicking a row opens a detail panel that slides in from the right showing the full connection record.

Analyses

A scrollable list of analysis cards. Each card shows a risk badge (low / medium / high, color-coded), timestamp, AI provider and model, connection count, and a plain-language summary. Destination IPs mentioned in the summary text are clickable — clicking one filters the Connections view to that IP.

Flagged connections are grouped by process, then by destination. Each process entry shows the raw process name and, where known, a resolved full name in parentheses (e.g. Code H (VS Code Helper)). Each destination row shows the hostname or IP, port with a protocol label (e.g. 443 HTTPS), and a connection count badge. Clicking a destination with a single connection opens the detail panel; clicking one with multiple connections filters the Connections view by that destination IP.

Process names are resolved via public/process-labels.json — a plain JSON file you can extend without rebuilding.

Stats

Stat tiles show key numbers: total connections, analyses, sessions, oldest record, and database size. CSS bar charts show:

• Protocol distribution (TCP / UDP)
• Direction distribution (outbound / inbound / local)
• Top 10 processes by connection count
• Top 10 countries by connection count
• Top 10 destinations by connection count

Configuration

Key	Default	Description
server.port	3311	HTTP server port
server.host	127.0.0.1	Bind address. Set to 0.0.0.0 to listen on all interfaces
server.openBrowser	true	Open browser automatically on start
server.ssePollInterval	2000	SSE poll interval in milliseconds
db.path		Absolute path to the SQLite database file

Edit ~/.wiremonitor/config.json to set values:

{
  "server": {
    "port": 3311,
    "host": "127.0.0.1",
    "openBrowser": true,
    "ssePollInterval": 2000
  },
  "db": {
    "path": "/path/to/your/database.db"
  }
}

Or pass flags at startup:

Flag	Description
--port <n>	HTTP server port
--host <host>	Bind address
--no-open	Do not open the browser on start
--db <path>	Path to the SQLite database file
--config	Print current configuration and exit

Storage

Default root:

~/.wiremonitor/

Path	Description
~/.wiremonitor/config.json	wiremonitor configuration

Override the root:

export WIREMONITOR_HOME=/path/to/custom/root

API

wiremonitor exposes a local REST API on the same port as the dashboard.

Method	Path	Description
GET	/api/connections	List connections
GET	/api/connections/:id	Single connection detail
GET	/api/analyses	List analyses
GET	/api/stats	Database statistics
GET	/api/status	Daemon status
GET	/api/events	SSE stream — emits connection events as new records arrive

All endpoints return JSON.

Query Parameters

GET /api/connections accepts:

Parameter	Description
limit	Number of results (default: 100, max: 1000)
offset	Pagination offset
since	Unix timestamp in milliseconds — return connections after this time
protocol	Filter by protocol: TCP or UDP
direction	Filter by direction: inbound, outbound, or local
process	Filter by process name (exact match)
dst_ip	Filter by destination IP

Agent Integration

OpenClaw Skill

Once installed globally (npm install -g wiremonitor), add a SKILL.md to your workspace:

---
name: wiremonitor
description: View live network connections, AI analyses, and traffic statistics in a browser dashboard
version: 1.0.0
requires_binaries:
  - wm
---

When the user asks about network traffic or wants to view connections visually, use the wiremonitor API:

- To fetch recent connections: GET http://localhost:3311/api/connections
- To get connection detail: GET http://localhost:3311/api/connections/:id
- To list AI analyses: GET http://localhost:3311/api/analyses
- To get database stats: GET http://localhost:3311/api/stats
- To check daemon status: GET http://localhost:3311/api/status

Tech Stack

Tool	Purpose
TypeScript	Language
Node.js 22+	Runtime
better-sqlite3	Read-only SQLite access
node:http	HTTP server, no framework
Vanilla JS / HTML / CSS	Dashboard, no frontend framework, no build step
Server-Sent Events	Real-time connection streaming
Vitest	Testing
Biome	Lint and format
tsup	Build

File Structure

wiremonitor/
├── src/
│   ├── server.ts              entry point — starts HTTP server, opens browser
│   ├── types.ts               shared TypeScript types
│   └── lib/
│       ├── config.ts          configuration load, save, and validation
│       ├── db.ts              read-only SQLite queries
│       ├── router.ts          HTTP request routing
│       ├── sse.ts             Server-Sent Events connection manager
│       └── api/
│           ├── connections.ts GET /api/connections, GET /api/connections/:id
│           ├── analyses.ts    GET /api/analyses
│           ├── stats.ts       GET /api/stats
│           └── status.ts      GET /api/status
├── public/
│   ├── index.html             dashboard shell
│   ├── app.js                 dashboard logic (vanilla JS)
│   ├── style.css              styles
│   └── process-labels.json    process name resolution map (extend without rebuilding)
├── tests/
│   ├── config.test.ts
│   ├── db.test.ts
│   ├── router.test.ts
│   └── sse.test.ts
├── package.json
├── tsconfig.json
├── tsup.config.ts
├── vitest.config.ts
├── biome.json
├── LICENSE
└── README.md

Development

git clone https://github.com/psandis/wiremonitor.git
cd wiremonitor
pnpm install
pnpm build
npm link

After npm link, run wm to start the dashboard.

pnpm test
pnpm typecheck
pnpm lint

Testing

pnpm test

Current bar:

• 64 tests across config, db, router, and sse modules
• integration tests use a real HTTP server on port 0 and a real seeded SQLite database
• SSE tests use fake timers to verify poller behavior without real delays

Related

• 🦀 Wirewatch — Network traffic capture daemon with AI anomaly detection
• 🦀 Psclawmcp — MCP server for the OpenClaw CLI ecosystem
• 🦀 Feedclaw — RSS/Atom feed reader and AI digest builder
• 🦀 Dustclaw — Find out what is eating your disk space
• 🦀 Driftclaw — Deployment drift detection across environments
• 🦀 Dietclaw — Codebase health monitor
• 🦀 Mymailclaw — Email scanner, categorizer, and cleaner
• 🦀 OpenClaw — The open source AI assistant

License

See MIT