Traffic Inspector

🌍 View in other languages

Traffic Inspector

Traffic Inspector is OmniRoute's built-in HTTPS traffic debugger — a Charles Proxy / mitmweb / HTTP Toolkit-like tool that is LLM-aware and agent-aware. It lives at /dashboard/tools/traffic-inspector and receives live traffic from up to 4 simultaneous capture sources.

Dashboard location: /dashboard/tools/traffic-inspector Sidebar group: Tools (after AgentBridge) See also: AGENTBRIDGE.md — AgentBridge is capture mode 1.

§1 Overview

What makes Traffic Inspector unique

Feature	mitmweb	Charles	Fiddler	OmniRoute Traffic Inspector
Web-based	✓	✗	✗	✓
Open-source	✓	✗	partial	✓
Agent-aware (knows if request is from Antigravity/Copilot/etc.)	✗	✗	✗	✓
LLM-aware (parses OpenAI/Anthropic/Gemini shape, tokens, model)	✗	✗	✗	✓
Model mapping visible (gemini-3-flash → claude-sonnet-4.7)	✗	✗	✗	✓
Proxy/upstream latency split	partial	✗	✗	✓
Integrated with OmniRoute routing, fallback, cost	✗	✗	✗	✓
System-wide proxy debug (any app on the machine)	✓	✓	✓	✓
Custom host capture (per-host DNS redirect)	✓	✓	✓	✓
HTTP_PROXY env mode	✓	✓	✓	✓
Conversation view (multi-turn bubbles, tool_use/tool_result)	✗	✗	✗	✓
SSE stream merger (reconstruct from delta events)	✗	✗	✗	✓
Session recording (named, exportable .har/.jsonl)	✗	✓	✓	✓

Architecture in one paragraph

The TrafficBuffer (src/mitm/inspector/buffer.ts) is a shared in-memory ring buffer (default 1000 entries, configurable via INSPECTOR_BUFFER_SIZE). All capture sources write to it via push(). The buffer classifies each entry using kindDetector.ts (determines if it's an LLM request), computes a contextKey (SHA-256 fingerprint of the system prompt), and broadcasts to all WebSocket subscribers via globalTrafficBuffer.subscribe(). The dashboard connects via GET /api/tools/traffic-inspector/ws and receives a snapshot on connect, followed by new/update/clear events.

§2 Capture modes

Traffic Inspector supports 4 simultaneous capture sources. Each is independently toggleable.

Mode 1 — AgentBridge (default, always on)

Source: AgentBridge handlers (src/mitm/handlers/base.ts) Mechanism: Every intercept() call in MitmHandlerBase calls hookBufferStart() before forwarding and hookBufferUpdate() on completion. Zero extra config — works as soon as AgentBridge is running. Reach: The 9 IDE agents configured in AgentBridge Note: source field in InterceptedRequest = "agent-bridge"

Mode 2 — Custom Hosts (DNS redirect)

Source: User-defined host list (inspector_custom_hosts table) Mechanism: Adding a host via the UI adds 127.0.0.1 <host> to /etc/hosts (requires sudo). The existing AgentBridge MITM server (port 443) generates a SNI cert dynamically for the new host. Reach: Any application using the added host — no app config change needed Note: source = "custom-host"

Example use cases:

Monitor api.openai.com from Python scripts
Debug my-internal-llm.company.com
Capture traffic from mobile devices on the same network (via ARP spoofing — advanced)

Mode 3 — HTTP_PROXY listener (port 8080)

Source: Applications using HTTP_PROXY/HTTPS_PROXY environment variables Mechanism: Secondary listener at port 8080 (src/mitm/inspector/httpProxyServer.ts) that acts as a standard explicit HTTP/HTTPS proxy. Accepts CONNECT tunnels (HTTPS) and direct HTTP requests. Reach: Any application that respects HTTP_PROXY env — no DNS change, no sudo Note: source = "http-proxy"

# Quick capture for a single command:
HTTPS_PROXY=http://127.0.0.1:8080 curl https://api.openai.com/v1/models

# Persistent capture in a shell session:
export HTTP_PROXY=http://127.0.0.1:8080
export HTTPS_PROXY=http://127.0.0.1:8080

TLS limitation: HTTPS CONNECT tunnels are captured as metadata only (host, port, timing) — TLS body is not decrypted by default. Enable "Decrypt HTTPS in proxy mode" toggle (opt-in, requires AgentBridge cert to be trusted) for full body inspection.

Port conflict: If port 8080 is in use, AgentBridge returns a 409 with a structured error. Change the port via INSPECTOR_HTTP_PROXY_PORT env var.

Mode 4 — System-wide proxy (advanced, opt-in)

Source: OS-level proxy settings (applies to all apps on the machine) Mechanism: Uses OS APIs to redirect all HTTP/HTTPS traffic through the HTTP_PROXY listener:

macOS: networksetup -setwebproxy / -setsecurewebproxy
Linux: gsettings set org.gnome.system.proxy + /etc/environment
Windows: netsh winhttp set proxy 127.0.0.1:8080 Reach: Every application on the machine that respects system proxy settings Note: source = "system-proxy"

Safety mechanisms:

Auto-disable timer (default 30 min, configurable via INSPECTOR_SYSTEM_PROXY_GUARD_MINUTES)
Previous system proxy state is saved in DB and restored on revert
Dashboard shows "Reverting system proxy" prompt if user navigates away while active
UI shows ⚠ Advanced badge + explicit confirmation checkbox

Capture mode comparison

Mode	Setup	Sudo?	Reach	Notes
1. AgentBridge	Automatic	Once (cert+hosts)	9 IDE agents	Default on
2. Custom Hosts	Per-host input	Yes (hosts file)	Any app using that host	Persisted in DB
3. HTTP_PROXY	`export HTTPS_PROXY=...`	No	Apps respecting env	Port 8080, no TLS decrypt by default
4. System-wide	Toggle + confirm	Yes	All apps on machine	Auto-disable in 30 min

§3 UI

3.1 Layout

┌─ Traffic Inspector ─────────────────────────────────────────────────────┐
│ ┌─ Capture sources toolbar ─────────────────────────────────────────┐   │
│ │ [✓ AgentBridge]  [✓ Custom hosts (3)]  [○ HTTP_PROXY]  [○ System]│   │
│ └─────────────────────────────────────────────────────────────────────┘  │
│ ┌─ Filter/control bar ──────────────────────────────────────────────┐   │
│ │ Profile: (●) LLM only  (○) Custom  (○) All                        │   │
│ │ [⎉ Pause] [🗑 Clear] [⬇ .har] [● REC session]    ● live 482/1k  │   │
│ └─────────────────────────────────────────────────────────────────────┘  │
├══◀▶══════════════════════════════╬══════════════════════════════════════╤╡
│ REQUEST LIST (resizable)         ║ DETAIL PANE                         ▲ │
│ ────────────────────────────── │ ║ [Conversation][Headers][Request]    │ │
│ ▎ 14:32 POST 200 12k AG openai ║ [Response][Timing][LLM][Stats]      │ │
│ ▎ 14:31 POST 200 8k  CP openai ║                                     ▼ │
│ ▎ 14:31 POST 503 ⚠   KR ...   ║                                       │
│ ▎ 14:30 GET  200 3k  🌐 custom ║                                       │
└══════════════════════════════════╝══════════════════════════════════════╝

3.2 Request list (left panel)

Virtualized (useVirtualList + ResizeObserver): handles 1000 items without freezing
Auto-scroll with toggle to pause while inspecting
Color-coded status: green (2xx), yellow (3xx), red (4xx/5xx), gray (in-flight)
Agent emoji: 🔵 Antigravity, 🟢 Copilot, 🟠 Kiro, 🟣 Codex, 🔷 Cursor, 🟤 Zed, 🟡 Claude Code, ⚫ Open Code, 🌐 custom host
Context color bar: 1px left border colored by contextKey (SHA-256 of system prompt) — visually groups related conversations
Lazy body: only the selected request's body is materialized in the detail tabs (avoids rendering 1000 × 1MB bodies)

3.3 Detail pane — 7 tabs

Tab	Content	Notes
Conversation	Multi-turn chat bubbles (system/user/assistant + tool_use/tool_result)	Normalized from any provider format; only shown for `detectedKind === "llm"`
Headers	Request + response header tables	Sensitive headers (Authorization, Cookie, api-key) masked by default; "Show secrets" toggle
Request	Raw body, JSON tree view, model field badge	Pretty-printed JSON or raw text
Response	Raw body or SSE event list; toggle "Raw ↔ Merged"	SSE merger reconstructs final message from delta events
Timing	Waterfall: proxy overhead vs upstream latency	Total, TTFB, and size
LLM Details	Provider, model, messages count, tokens in/out, cost estimate, mapped target	Only shown for LLM requests
Stats	Recharts: latency timeline, token bar chart, tool call scatter	Only shown when a recorded session is loaded

3.4 Toolbar controls

Control	Action
⎉ Pause	Stops rendering new requests; "X new" badge accumulates
🗑 Clear	Clears the UI list (server buffer is not affected)
⬇ Export .har	Downloads current filtered list as HAR file
● Record session	Starts a named recording session
Profile selector	LLM only / Custom hosts / All
Host filter	Substring match on `host` field
Agent filter	Dropdown: All / per-agent
Status filter	All / 2xx / 3xx / 4xx / 5xx / error
Source filter	All / agent-bridge / custom-host / http-proxy / system-proxy

3.5 Resizable panels

List and detail pane separated by a drag handle
List width: min 280px, max 720px, persisted in localStorage (inspector.listWidth)
Collapsible to a 48px rail (icon-only); click a row in the rail to expand

§4 LLM-aware features

4.1 Kind detector (`src/mitm/inspector/kindDetector.ts`)

Classifies each request as "llm", "app", or "unknown" using 4 signals:

Host registry — ~18 known LLM API hostnames (OpenAI, Anthropic, Gemini, Groq, Mistral, Together, Fireworks, Cohere, Perplexity, Hugging Face, OpenRouter, xAI, Moonshot, etc.)
Path patterns — /v1/chat/completions, /v1/messages, /generateContent, /v1/responses, etc.
Body shape — detects messages[] (OpenAI/Claude), contents[] (Gemini), prompt, input fields
User-agent hints — codex, claude, gemini, antigravity, kiro, copilot, cursor in UA string

Custom hosts added via Mode 2 inherit their kind from the form input (defaults to "custom").

4.2 SSE merger (`src/mitm/inspector/sseMerger.ts`)

MIT port from chouzz/llm-interceptor

Reconstructs the final assistant message from raw SSE delta events:

Anthropic: accumulates content_block_delta by index; handles text_delta, input_json_delta (tool calls), thinking_delta
OpenAI: accumulates choices[i].delta.content and tool_calls by index
Gemini: accumulates candidates[i].content.parts
Unknown: returns raw events as-is

The Response tab shows a toggle: "Raw events ↔ Merged".

4.3 Conversation normalizer (`src/mitm/inspector/conversationNormalizer.ts`)

MIT port from chouzz/llm-interceptor

Converts OpenAI, Anthropic, and Gemini message formats to a single NormalizedConversation before rendering:

interface NormalizedConversation {
  request: NormalizedTurn[];    // messages / contents / prompt from request body
  response: NormalizedTurn[];   // assistant response (merged via sseMerger)
  contextKey: string | null;    // SHA-256 system-prompt fingerprint
}

Block types: text, tool_use, tool_result. The Conversation tab uses this shape regardless of provider.

4.4 Context key colorization (`src/mitm/inspector/contextKey.ts`)

Computes SHA-256 of the system prompt (first role:system message, or system field, or Gemini systemInstruction)
Returns a 12-character hex prefix ("a3f9c2...")
Frontend maps the key to a deterministic HSL color for the left-border bar
Filtro "same context": clicking the ctx #a3f chip adds a filter to show only requests with the same fingerprint

This makes it easy to visually distinguish different "personas" or tasks running in the same agent session.

4.5 LLM metadata extraction

For LLM requests, the LLM Details tab extracts:

interface LlmMetadata {
  provider: string | null;        // "openai" | "anthropic" | "gemini" | ...
  apiKind: string | null;         // "chat.completions" | "messages" | "embeddings" | ...
  model: string | null;           // from request body or response
  messages: number;               // turn count
  tokensIn: number | null;        // usage.prompt_tokens / usage.input_tokens
  tokensOut: number | null;       // usage.completion_tokens / usage.output_tokens
  streamed: boolean;              // true if SSE response
  mappedTo: string | null;        // x-omniroute-mapped header
  costEstimateUsd: number | null; // estimated cost based on OmniRoute pricing
}

§5 Sessions

5.1 Recording a session

Click "● Record session" in the toolbar → enter a name (optional)
Live tail continues normally; a red pulsing indicator shows ◉ REC · <name> · 00:42 · 23 reqs
Click "⏹ Stop" → the session snapshot is saved to inspector_sessions + inspector_session_requests

5.2 Viewing a recorded session

The Sessions dropdown in the toolbar lists saved sessions. Selecting one:

Loads the session's snapshot (frozen state)
A banner shows: Viewing recorded session "<name>" — [Back to live]
The Stats tab becomes available with Recharts aggregates

5.3 Export formats

Each session can be exported as:

Format	Use
HAR (HTTP Archive 1.2)	Compatible with Chrome DevTools, Charles, Fiddler — import for offline analysis
JSONL	One `InterceptedRequest` per line — compatible with `llm-interceptor` format

Export via GET /api/tools/traffic-inspector/sessions/{id}/export.har or the ⬇ button in the Sessions dropdown.

§6 Security

Traffic Inspector shows all intercepted HTTPS traffic, including authorization headers and request bodies. The following controls are in place:

Control	Details
LOCAL_ONLY	All routes and the WebSocket endpoint are loopback-only (enforced in `routeGuard.ts` before auth)
Secret masking	`maskSecrets()` applied to all headers and bodies before `TrafficBuffer.push()` — enabled by default (`INSPECTOR_MASK_SECRETS=true`)
Body size cap	Bodies > `INSPECTOR_MAX_BODY_KB` (default 1024 KB) are truncated with `"(truncated for performance)"` notice
Sensitive header masking	`authorization`, `cookie`, `api-key`, `x-api-key`, `proxy-authorization` → `Bearer ***` in Headers tab; "Show secrets" toggle
CSP	Strict Content Security Policy on Traffic Inspector pages to prevent XSS via injected response bodies
No persistence by default	The `TrafficBuffer` is in-memory and lost on server restart. Sessions are persisted only when explicitly recorded

Hard Rules applied

Rule	Application
#12 `sanitizeErrorMessage`	All HTTP error responses from Traffic Inspector routes are sanitized
#15 + #17 `isLocalOnlyPath()`	`/api/tools/traffic-inspector/` is LOCAL_ONLY + SPAWN_CAPABLE (system proxy commands)

Known limitations

System-wide proxy mode affects all applications on the machine, including VPN clients and SSO. Always use with the auto-disable timer. Do not use on shared machines.
CONNECT tunnel HTTPS: Mode 3 (HTTP_PROXY) captures only tunnel metadata for HTTPS destinations unless TLS interception is enabled. This is by design — transparent capture without the AgentBridge cert being trusted would break TLS verification for those apps.
Hardcoded strings in some components: Some UI components (F7/F8) have a small number of hardcoded strings not yet covered by i18n keys. These are documented as a Known Limitation in the i18n gap report; they will be migrated in a follow-up pass. Affected strings are UI decorative labels that don't require translation for functional use.

§7 Troubleshooting

WebSocket disconnection

If the live tail shows "Disconnected":

Check the server is still running: GET /api/tools/traffic-inspector/capture-modes
Reload the page — the WebSocket reconnects and receives a fresh snapshot
If the server was restarted, the in-memory buffer was cleared — old entries are gone unless a session was recorded

Port 8080 conflict

If HTTP_PROXY mode fails to start:

lsof -i :8080    # find the process

Change the port:

# .env
INSPECTOR_HTTP_PROXY_PORT=8888

System proxy not reverted

If OmniRoute crashes while system-wide proxy mode is active:

macOS:

networksetup -setwebproxystate Wi-Fi off
networksetup -setsecurewebproxystate Wi-Fi off

Linux (GNOME):

gsettings set org.gnome.system.proxy mode 'none'

Windows:

netsh winhttp reset proxy

The dashboard will also offer "Revert system proxy" on next load if it detects the DB state indicates proxy was active.

Buffer full

When the buffer reaches INSPECTOR_BUFFER_SIZE (default 1000), new entries rotate out the oldest. If important requests are being lost:

Increase INSPECTOR_BUFFER_SIZE (e.g., 5000) — trades memory for retention
Record a session to persist the relevant window to DB

§8 API reference

All routes are LOCAL_ONLY (loopback-only) and SPAWN_CAPABLE (system proxy commands). See src/server/authz/routeGuard.ts.

Base path: /api/tools/traffic-inspector/

Request management

Method	Path	Description
GET	`/requests`	List requests (filterable: `?profile=llm&host=&agent=&status=&source=&sessionId=`)
GET	`/requests/{id}`	Single request details
DELETE	`/requests`	Clear the in-memory buffer
POST	`/requests/{id}/replay`	Re-execute the same request through OmniRoute router
PUT	`/requests/{id}/annotation`	Save or update a note on a request

WebSocket

Method	Path	Description
GET	`/ws`	Live WebSocket stream. Sends `snapshot` on connect, then `new`/`update`/`clear` events

Export

Method	Path	Description
GET	`/export.har`	Export current filtered list as HAR 1.2

Custom hosts

Method	Path	Description
GET	`/hosts`	List custom hosts
POST	`/hosts`	Add host (auto-edits `/etc/hosts`)
DELETE	`/hosts/{host}`	Remove host
PATCH	`/hosts/{host}`	Toggle `enabled`

Capture modes

Method	Path	Description
GET	`/capture-modes`	State of all 4 capture modes
POST	`/capture-modes/http-proxy`	Start/stop HTTP_PROXY listener (`{action: "start"\|"stop"}`)
POST	`/capture-modes/system-proxy`	Apply/revert system-wide proxy (`{action: "apply"\|"revert"}`)
POST	`/capture-modes/tls-intercept`	Toggle HTTPS body decryption in proxy mode

Sessions

Method	Path	Description
POST	`/sessions`	Start recording (`{name?: string}`)
PATCH	`/sessions/{id}`	Stop or rename (`{action: "stop"\|"rename", name?: string}`)
GET	`/sessions`	List all saved sessions
GET	`/sessions/{id}`	Session snapshot (all requests)
DELETE	`/sessions/{id}`	Delete session
GET	`/sessions/{id}/export.har`	Export session as HAR 1.2

Internal ingest (D4 fallback)

Method	Path	Description
POST	`/internal/ingest`	Accepts intercepted request from `server.cjs` passthrough path; requires `INSPECTOR_INTERNAL_INGEST_TOKEN` header

Full OpenAPI schemas: docs/reference/openapi.yaml → tag Traffic Inspector.

Uh oh!

Traffic Inspector

Traffic Inspector

§1 Overview

What makes Traffic Inspector unique

Architecture in one paragraph

§2 Capture modes

Mode 1 — AgentBridge (default, always on)

Mode 2 — Custom Hosts (DNS redirect)

Mode 3 — HTTP_PROXY listener (port 8080)

Mode 4 — System-wide proxy (advanced, opt-in)

Capture mode comparison

§3 UI

3.1 Layout

3.2 Request list (left panel)

3.3 Detail pane — 7 tabs

3.4 Toolbar controls

3.5 Resizable panels

§4 LLM-aware features

4.1 Kind detector (src/mitm/inspector/kindDetector.ts)

4.2 SSE merger (src/mitm/inspector/sseMerger.ts)

4.3 Conversation normalizer (src/mitm/inspector/conversationNormalizer.ts)

4.4 Context key colorization (src/mitm/inspector/contextKey.ts)

4.5 LLM metadata extraction

§5 Sessions

5.1 Recording a session

5.2 Viewing a recorded session

5.3 Export formats

§6 Security

Hard Rules applied

Known limitations

§7 Troubleshooting

WebSocket disconnection

Port 8080 conflict

System proxy not reverted

Buffer full

§8 API reference

Request management

WebSocket

Export

Custom hosts

Capture modes

Sessions

Internal ingest (D4 fallback)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

4.1 Kind detector (`src/mitm/inspector/kindDetector.ts`)

4.2 SSE merger (`src/mitm/inspector/sseMerger.ts`)

4.3 Conversation normalizer (`src/mitm/inspector/conversationNormalizer.ts`)

4.4 Context key colorization (`src/mitm/inspector/contextKey.ts`)