# Traffic

###### Read captured request and response traffic from the terminal or an AI agent.

LocalCan's inspector records the HTTP traffic flowing through your proxy and Public URLs (tunnels). The `localcan traffic` commands expose that data on the command line, and `localcan mcp` exposes it to AI agents over the Model Context Protocol. Both read the exact same captured exchanges as the desktop inspector.

Capture is off by default and lives in memory only. The inspector keeps the most recent 250 exchanges and clears them when the daemon restarts. Turn it on with `localcan traffic enable`.

An exchange is recorded once its response completes, so a slow or still-running request does not appear in `ls` or `watch` until it finishes. WebSocket connections are the exception and appear when the connection opens.

#### Commands

##### `localcan traffic status`

Show whether capture is on, how many exchanges are buffered, and how much memory and disk they use.

##### `localcan traffic enable` and `localcan traffic disable`

Turn traffic capture on or off.

##### `localcan traffic clear`

Drop all captured traffic.

##### `localcan traffic ls [filters]`

List recent exchanges, newest first, then exit. Columns: `ID`, `TIME`, `METHOD`, `STATUS`, `DUR`, `PATH`, `HOST`. Narrow the results with the filters below. With `--json` each row is one NDJSON object:

```json
{"id":"9f3a1c2d4e5f60718293a4b5c6d7e8f0","method":"POST","status":201,"path":"/v1/orders","host":"my-app-12.localcan.dev","project_id":"my-app","duration_ms":37,"req_bytes":18,"resp_bytes":120,"replayed":false,"time":"2026-06-29T10:14:22Z"}
```

##### `localcan traffic get <id> [--format <fmt>] [--redact]`

Export one exchange. The `<id>` can be the full id or any unique prefix, such as the short id shown by `traffic ls`. The `--format` is one of `markdown` (default), `curl`, `http`, `har`, or `json`. Output is written verbatim, so you can redirect or pipe it:

```sh
localcan traffic get 9f3a1c2d --format har > exchange.har
localcan traffic get 9f3a1c2d --format curl | sh
```

Exports include real header and cookie values by default. You ran the command and the data goes to your own terminal. Pass `--redact` to strip sensitive headers (Authorization, cookies, API keys). URLs and bodies are not redacted. The global `--json` flag is shorthand for `--format json`.

##### `localcan traffic watch [filters]`

Stream new exchanges live as they complete, until you press Ctrl-C. Takes the same filters as `ls`, except `--last` (there is no backlog, `ls` covers history). With `--json` each line is an NDJSON event carrying `"event":"exchange"`:

```sh
localcan traffic watch --status 5xx --json | jq .
```

#### Filters

`ls` and `watch` take the same filters, and a row must match every one you pass. The exception is `--last`, which applies only to the `ls` snapshot.

- `--last N`: cap the number of rows (`ls` only, default 20). Rows are newest first.
- `--host SUBSTRING`: case-insensitive substring of the public host the client connected to (the `*.localcan.dev`, `.local`, or custom domain), captured before any Host rewrite for your backend. For example, `--host my-app` matches `my-app-12.localcan.dev`.
- `--project ID`: exact project id, such as `my-app` (not the display name).
- `--method METHOD`: exact HTTP method, case-insensitive, such as `--method post`.
- `--status STATUS`: match the response status. Accepts an exact code (`200`, `404`, `500`) or a class (`1xx`, `2xx`, `3xx`, `4xx`, `5xx`) covering any code in that range. Exchanges still in flight match no status filter.

Examples:

```sh
# Newest 50 failed requests to one Public URL
localcan traffic ls --status 5xx --host my-app-12.localcan.dev --last 50

# Live POSTs that returned any 4xx, as NDJSON piped to jq
localcan traffic watch --method POST --status 4xx --json | jq .

# Everything for one project
localcan traffic ls --project my-app
```

#### Read it from an AI agent

AI agents can read this same captured traffic. An agent that runs shell commands can use `traffic ls --json` and `traffic get`, and agents that speak the Model Context Protocol get first-class tools through `localcan mcp`. See [AI agents](/docs/ai-agents/overview) for both paths and per-host setup.

#### What an export represents

A captured request is the request LocalCan forwarded to your backend, not a byte-for-byte copy of the original client request. The exported `url` is the backend target, and the headers include LocalCan's `x-forwarded-*` plus any rewritten Host or injected values. The reconstructed client-facing address is reported separately as `public_url`. A cURL export therefore reproduces the request against your backend, which is what you usually want when debugging a handler.