Network inspection

Mobilerun can inspect a device’s network traffic and stream decoded HTTP/1.1, HTTP/2, HTTP/3, and application WebSocket events to your local machine. The stream is live-only and does not require adb or direct access to the device. Unlike the ADB and Frida tunnels, network inspection is session-based. You start a session with the REST API, connect to the returned WebSocket with a short-lived viewer token, and stop the session when you are finished.

Requirements

Network inspection must be enabled for the device’s hosting pool. Contact Mobilerun support at contact@mobilerun.ai if you need access.

A Mobilerun API key (dr_sk_...)
curl, jq, and websocat installed locally

Set the API key and device ID in your shell:

export MOBILERUN_API_KEY='dr_sk_...'
export DEVICE_ID='YOUR_DEVICE_ID'
export MOBILERUN_API='https://api.mobilerun.ai/v1'

Check whether the device supports network inspection:

curl --fail-with-body -sS \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" \
  "$MOBILERUN_API/devices/$DEVICE_ID/capabilities" \
  | jq '.capabilities.trafficInspection'

The value must be true. The capability is granted when a device is placed in an enabled pool. Disabling inspection for that pool also prevents new sessions and stops active sessions.

Endpoints

Method	Endpoint	Purpose
`POST`	`/v1/devices/{deviceId}/traffic/sessions`	Start a session and receive stream credentials.
`GET`	`/v1/devices/{deviceId}/traffic/sessions`	List recent session metadata.
`GET`	`/v1/devices/{deviceId}/traffic/sessions/{sessionId}`	Read status and issue fresh stream credentials.
`DELETE`	`/v1/devices/{deviceId}/traffic/sessions/{sessionId}`	Stop a session and restore device networking.
`WSS`	Returned as `stream.url`	Receive live decoded traffic events.

Use your Mobilerun API key for the REST endpoints. The WebSocket uses the session-scoped viewer token returned in stream.token; always connect to the returned stream.url instead of constructing it yourself.

Start an inspection session

Create a session with a unique Idempotency-Key so retrying the same request does not start another session:

export REQUEST_ID="traffic-$(date +%s)-$$"

SESSION="$(
  curl --fail-with-body -sS -X POST \
    -H "Authorization: Bearer $MOBILERUN_API_KEY" \
    -H "Idempotency-Key: $REQUEST_ID" \
    -H 'Content-Type: application/json' \
    -d '{"expiresInSeconds":3600,"maxBodyBytes":1048576}' \
    "$MOBILERUN_API/devices/$DEVICE_ID/traffic/sessions"
)"

export SESSION_ID="$(jq -er '.id' <<<"$SESSION")"
jq '{id, state, expiresAt, maxBodyBytes, retention}' <<<"$SESSION"

expiresInSeconds can be 60–14400 seconds and defaults to 3600. maxBodyBytes can be 0–10485760 bytes and defaults to 1048576. Set it to 0 to receive request and response metadata without body content. Only one session can be starting, active, or stopping for a device at a time. Starting another returns 409 TRAFFIC_ALREADY_ACTIVE.

Wait until the session is active

Starting inspection is asynchronous. Poll the status endpoint until the device producer is ready:

while true; do
  STATUS="$(
    curl --fail-with-body -sS \
      -H "Authorization: Bearer $MOBILERUN_API_KEY" \
      "$MOBILERUN_API/devices/$DEVICE_ID/traffic/sessions/$SESSION_ID"
  )"

  STATE="$(jq -er '.state' <<<"$STATUS")"
  [ "$STATE" = 'active' ] && break

  if [ "$STATE" != 'starting' ]; then
    jq . <<<"$STATUS"
    exit 1
  fi

  sleep 1
done

export STREAM_URL="$(jq -er '.stream.url' <<<"$STATUS")"
export VIEWER_TOKEN="$(jq -er '.stream.token' <<<"$STATUS")"
export STREAM_PROTOCOL="$(jq -er '.stream.protocol' <<<"$STATUS")"

The status response issues a fresh, short-lived viewer token while the session is starting or active. The token is restricted to this owner, device, and session. Use it only for the returned stream URL; do not substitute your Mobilerun API key.

Stream events with websocat

Open the returned WebSocket URL with the viewer token and required subprotocol:

websocat \
  -H="Authorization: Bearer $VIEWER_TOKEN" \
  -H="Sec-WebSocket-Protocol: $STREAM_PROTOCOL" \
  "$STREAM_URL" \
  | jq --unbuffered -c .

Exercise the app on the device while this command is running. Each line is a JSON event. The first event is hello; subsequent event types are:

Type	Meaning
`ready`	The on-device traffic producer connected.
`flow`	A decoded HTTP exchange or an interception failure.
`websocket-message`	An application WebSocket message associated with a flow.
`gap`	Events were dropped because the bounded device queue overflowed.

Request and response bodies appear as request_body_base64 and response_body_base64. WebSocket payloads appear as payload_base64. Headers remain arrays of name-value pairs so repeated headers are preserved. For example, decode response bodies with jq:

websocat \
  -H="Authorization: Bearer $VIEWER_TOKEN" \
  -H="Sec-WebSocket-Protocol: $STREAM_PROTOCOL" \
  "$STREAM_URL" \
  | jq --unbuffered -r \
      'select(.type == "flow" and .flow.response_body_base64) | .flow.response_body_base64 | @base64d'

Inspected headers and bodies can contain credentials, personal data, and other secrets. Mobilerun does not retain session events, but anything you print, pipe, or redirect locally may be stored on your machine.

Stop the session

Stop inspection when you are finished so the device can restore its normal routing and temporary trust changes:

curl --fail-with-body -sS -X DELETE \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" \
  "$MOBILERUN_API/devices/$DEVICE_ID/traffic/sessions/$SESSION_ID" \
  | jq '{id, state}'

The request returns 202 Accepted while cleanup runs. Repeating it is safe. Sessions also stop automatically when they expire.

Troubleshooting

TRAFFIC_NOT_SUPPORTED — The device image does not support network inspection.
TRAFFIC_NOT_ENTITLED — capabilities.trafficInspection is false; create a device in an enabled pool or contact support.
TRAFFIC_ALREADY_ACTIVE — Another session is starting, active, or stopping. Use the session ID in details.sessionId, or list sessions with GET /devices/{deviceId}/traffic/sessions.
TRAFFIC_DEVICE_NOT_READY — Wait until the device reaches the ready state and retry with the same idempotency key.
401 Unauthorized on the WebSocket — Use a fresh .stream.token from the session status response, not the Mobilerun API key.
WebSocket subprotocol error — Send Sec-WebSocket-Protocol: mobilerun.traffic.v1 in addition to the viewer token.
The viewer token expired or the socket closed with 1013 — Read the session status again to mint a fresh token, then reconnect. Missed events are not replayed.

Introduction

Concepts

Guides

Dashboard

Agent Skills

Integrations

Network inspection

Requirements

Endpoints

Start an inspection session

Wait until the session is active

Stream events with websocat

Stop the session

Troubleshooting

​Requirements

​Endpoints

​Start an inspection session

​Wait until the session is active

​Stream events with websocat

​Stop the session

​Troubleshooting

Requirements

Endpoints

Start an inspection session

Wait until the session is active

Stream events with websocat

Stop the session

Troubleshooting