Capture & Replay Debugging

Record every HTTP request and response flowing through your tunnel. Inspect traffic in the dashboard, replay requests to reproduce bugs, and export captures for automated testing.

How It Works

When capture is enabled, the server records HTTP exchanges into a per-agent in-memory ring buffer. Each capture includes the full request (method, URL, headers, body) and response (status, headers, body, latency). Sensitive headers are automatically redacted.

Client ──► NFLTR Server ──► Agent
               │
          ┌────┴────┐
          │ Capture  │  Records: method, URL, headers, body,
          │ Buffer   │  status, latency, timestamp
          └─────────┘
               │
     ┌─────────┼─────────┐
     ▼         ▼         ▼
  Dashboard  Admin API  MCP Tools

Two Capture Modes

🖥️ Server-Side Capture

Enable CAPTURE_ENABLED=true on the server. Traffic is buffered in memory and viewable in the dashboard or via the Admin API. No agent changes needed.

📁 Client-Side Recording

Use nfltr http --record capture.json on the agent side. Traffic is written incrementally to a local JSON file for offline analysis and replay.

Server-Side Configuration

Variable	Default	Description
`CAPTURE_ENABLED`	`false`	Enable capture for all agents
`CAPTURE_MAX_REQUESTS`	`100`	Ring buffer size per agent
`CAPTURE_MAX_BODY_BYTES`	`8192`	Body truncation limit (8 KiB)
`CAPTURE_REDACT_HEADERS`	`Authorization,Cookie,X-Api-Key`	Headers to auto-redact

Admin API

Access captures via the admin API (port :8081):

Method	Endpoint	Description
`GET`	`/api/v1/traffic/{agentID}?limit=50`	List captures (newest first)
`GET`	`/api/v1/traffic/{agentID}/{id}`	Get single capture with full details
`POST`	`/api/v1/traffic/{agentID}/{id}/replay`	Re-issue request, return fresh response
`DELETE`	`/api/v1/traffic/{agentID}`	Clear all captures for an agent

Client-Side Recording

Record traffic to a JSON file on the agent side:

# Record all traffic to a file
nfltr http 8080 --record capture.json

# The file contains a JSON array of captured exchanges, updated incrementally

Replaying Traffic

Use nfltr replay to re-execute captured requests against any server:

# Replay all captured traffic against localhost
nfltr replay capture.json

# Replay against a different server
nfltr replay capture.json --target http://staging.example.com:3000

# Only replay POST requests
nfltr replay capture.json --method POST

# Filter by path with 100ms delay between requests
nfltr replay capture.json --path /api/users --delay 100

# Preview without executing
nfltr replay capture.json --dry-run

Replay flags

Flag	Default	Description
`--target`	`http://localhost:8080`	Base URL to replay against
`--delay`	`0`	Milliseconds between requests
`--method`	—	Filter by HTTP method
`--path`	—	Filter by URL path substring
`--dry-run`	`false`	Print without executing
`--verbose`	`false`	Print response bodies
`--preserve-host`	`false`	Send original Host header

Dashboard Integration

When capture is enabled, the dashboard shows a Traffic tab for each agent:

Open the dashboard and click an agent card
Select the Traffic tab
Browse recent requests — method, URL, status code, latency, size
Click any request to view full headers and body
Click Replay to re-issue and compare responses side-by-side

💡 MCP Integration

Captures can be accessed via MCP tools: list_traffic, get_traffic, clear_traffic, and replay_traffic — enabling AI-assisted debugging workflows.

⚠️ Memory Only

Server-side captures are stored in memory and evicted when the ring buffer is full (FIFO). They do not persist across server restarts. Use --record for persistent capture to a file.

Debug HTTP traffic with full visibility

Record, inspect, and replay every request flowing through your tunnel.

Download Agent Replay CLI →