Intercepting Traffic

Overview

The moqtap intercept command sits between your application and a MoQT relay, forwarding all traffic unmodified while parsing every MoQT frame inline.

Your App  ←→  moqtap intercept (listener)  ←→  Real Relay
                      ↓
              live terminal output + .moqtrace recording

Quick start

# Start intercepting — listens on 127.0.0.1:4443, forwards to upstream relay
moqtap intercept -u moqt://relay.example.com

# Point your app at localhost:4443 instead of the real relay

Options

Flag	Description
`-u, --upstream <URL>`	Upstream relay URL. Falls back to `MOQTAP_RELAY` or `.moqtap.toml`; with `--bridge` and none of these, only the browser’s sessions run
`-l, --listen <ADDR>`	Listen address (default: `127.0.0.1:4443`)
`--upstream-wt <URL>`	WebTransport upstream URL
`-o, --output <PATH>`	Record the relay’s sessions to a `.moqtrace` file (`-` for stdout)
`--filter <TYPE>`	Filter: `ctrl` (control messages only) or `data` (data streams only)
`--session <ID>`	Show only events for a specific session
`--format <FMT>`	Output format: `text` (default) or `json`
`-j, --json`	Shorthand for `--format json`
`--bridge`	Let the browser extension send a tab’s sessions through the CLI, impaired — see Impairing a Browser Tab
`-k, --insecure`	Skip upstream TLS verification
`--cert <PATH>`	Custom TLS certificate for listener
`--key <PATH>`	Custom TLS private key
`-q, --quiet`	Print only errors and warnings; the recording still goes to `--output`

Examples

# Record session to a .moqtrace file
moqtap intercept -u moqt://relay.example.com -o session.moqtrace

# Show only control messages
moqtap intercept -u moqt://relay.example.com --filter ctrl

# JSON output for scripting
moqtap intercept -u moqt://relay.example.com -j

The listener accepts both raw QUIC and WebTransport clients on the same address, so a browser-based client and a native one can both point at it.

Terminal output

Events are color-coded and timestamped:

12:34:56.789  #1  NEW     192.168.1.5:54321 connected
12:34:56.790  #1  C→R  SETUP   CLIENT_SETUP versions=[4278190087]
12:34:56.791  #1  R→C  SETUP   SERVER_SETUP version=4278190087
12:34:56.800  #1  C→R  CTRL    SUBSCRIBE req=1 ns=live track=video
12:34:56.801  #1  R→C  CTRL    SUBSCRIBE_OK req=1 alias=1

Color	Meaning
Green	`C→R` client to relay, `NEW` session start
Magenta	`R→C` relay to client
Cyan	`SETUP` handshake
Blue	`CTRL` control messages
Purple	`UNI` unidirectional data streams
Yellow	`OBJ` object headers, `DGRAM` datagrams
Red	`ERR` parse errors, `END` session close

TLS handling

For the listener: pass a TLS certificate (--cert / --key), or moqtap generates a self-signed one
For WebTransport clients: use serverCertificateHashes to pin the proxy’s cert
For upstream connections: use -k to skip verification for dev relays

Use cases

Debug your app’s MoQT behavior without modifying the app code
See both sides of the conversation (what your app sends vs. what the relay sends)
Record .moqtrace files for offline analysis or sharing with your team
Filter to control-only or data-only streams to focus on specific issues
Pipe JSON output to other tools for automated analysis
Run a browser tab’s sessions over a 3G, 4G or offline link: see Impairing a Browser Tab