Network Inspector Guide

Snap-O publishes Android libraries version 3.1.1 and newer to Maven Central. Most Android projects already include mavenCentral(); add it to your dependency sources if yours does not.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

Choose the dependency that matches your network client. Use the real interceptor in debug builds and its no-op counterpart in release builds. The no-op artifact preserves the same API while passing traffic through without starting the Snap-O server.

[versions]
snapo = "8.0.0"

[libraries]
snapo-network-okhttp3 = { module = "com.openai.snapo:network-okhttp3", version.ref = "snapo" }
snapo-network-okhttp3-noop = { module = "com.openai.snapo:network-okhttp3-noop", version.ref = "snapo" }

dependencies {
    debugImplementation(libs.snapo.network.okhttp3)
    releaseImplementation(libs.snapo.network.okhttp3.noop)
}

dependencies {
    debugImplementation("com.openai.snapo:network-okhttp3:8.0.0")
    releaseImplementation("com.openai.snapo:network-okhttp3-noop:8.0.0")
}

[versions]
snapo = "8.0.0"

[libraries]
snapo-network-httpurlconnection = { module = "com.openai.snapo:network-httpurlconnection", version.ref = "snapo" }
snapo-network-httpurlconnection-noop = { module = "com.openai.snapo:network-httpurlconnection-noop", version.ref = "snapo" }

dependencies {
    debugImplementation(libs.snapo.network.httpurlconnection)
    releaseImplementation(libs.snapo.network.httpurlconnection.noop)
}

dependencies {
    debugImplementation("com.openai.snapo:network-httpurlconnection:8.0.0")
    releaseImplementation("com.openai.snapo:network-httpurlconnection-noop:8.0.0")
}

Add the interceptor once when the client is created. Requests made by that client can then be captured and made available to Snap-O. WebSockets require the wrapped factory shown below.

OkHttp

import com.openai.snapo.network.okhttp3.SnapOOkHttpInterceptor

val client = OkHttpClient.Builder()
    .addInterceptor(SnapOOkHttpInterceptor())
    .build()

import com.openai.snapo.network.okhttp3.SnapOOkHttpInterceptor

val client = HttpClient(OkHttp) {
    engine {
        addInterceptor(SnapOOkHttpInterceptor())
    }
}

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(SnapOOkHttpInterceptor())
    .build()

val client = HttpClient(OkHttp) {
    engine {
        preconfigured = okHttpClient
    }
}

import com.openai.snapo.network.httpurlconnection.SnapOHttpUrlInterceptor

val interceptor = SnapOHttpUrlInterceptor()
val connection = interceptor.open(URL("https://example.com"))

connection.connect()
connection.inputStream.use { body ->
    // Read the response.
}
connection.disconnect()

val existing = URL("https://example.com")
    .openConnection() as HttpURLConnection
val connection = SnapOHttpUrlInterceptor().intercept(existing)

import com.openai.snapo.network.okhttp3.withSnapOInterceptor

val webSocketFactory = client.withSnapOInterceptor()
val webSocket = webSocketFactory.newWebSocket(request, listener)

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(SnapOOkHttpInterceptor())
    .build()

val client = HttpClient(OkHttp) {
    engine {
        preconfigured = okHttpClient
        webSocketFactory = okHttpClient.withSnapOInterceptor()
    }
    install(WebSockets)
}

1. Install and launch the debug build on an authorized Android device or emulator.
2. Open Snap-O on macOS and select the connected device.
3. Open Tools → Show App Inspector, use the toolbar inspector button, or press ⌘⌥I.
4. Find the app process in the picker and click its Network icon, then trigger a request in the Android app.
5. Open the request to inspect headers, bodies, timing, SSE, or WebSocket messages.

Each running app process has one picker row, with shortcuts for its available inspectors. At startup, Snap-O restores your last app and inspector when available, or selects another available app. During a session, it keeps captured requests visible through disconnects and reconnects when the selected app returns.

If the selected Android app stops, click Open app on the waiting screen when available, or launch it on your device.

Filter traffic

Right-click a request to add its host to the exclusion filter. Exclusion filters are saved across sessions. Use the settings button beside the exclusion summary to add or remove filters. You can also search requests without changing your saved filters.

Inspect responses

Use the arrow keys to move between requests. Server-Sent Events show whether the stream is pending, streaming, closed, or offline. When a response body is unavailable, Snap-O explains whether it is no longer retained or is not cached on this Mac. If loading fails while connected, click Retry.

Intercept requests

Use snapo network intercept to change a real API response or return mock data. The inspector shows the response delivered to the app while your Python handlers run separately. Follow the Network Interception guide for requirements, examples, and supported traffic.

• Confirm the device is online and authorized in adb devices.
• Confirm the installed variant includes the debug interceptor, not the no-op release artifact.
• Make sure the request uses the exact OkHttp client, Ktor engine, or HttpURLConnection wrapper you configured.
• Keep the Android app process running and select the newest process after an app restart.
• Update the Snap-O desktop app and Android dependency together if a protocol mismatch appears.
• The replay buffer retains up to five minutes, 10,000 events, or 16 MiB of total event data, whichever limit is reached first.
• Individual request and response bodies are captured up to 5 MiB by default; larger bodies are truncated.

Debug builds initialize the on-device server automatically through SnapONetworkInitProvider. Release builds do not start the server unless Network Inspector is explicitly enabled. Most apps should keep the defaults and use the no-op release artifact.

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <meta-data
            android:name="snapo.network.allow_release"
            android:value="true" />
    </application>
</manifest>

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application>
        <provider
            android:name="com.openai.snapo.network.SnapONetworkInitProvider"
            android:authorities="${applicationId}.snapo-network-init"
            android:exported="false">
            <meta-data
                android:name="snapo.auto_init"
                android:value="false"
                tools:replace="android:value" />
        </provider>
    </application>
</manifest>

import com.openai.snapo.network.NetworkInspector
import com.openai.snapo.network.NetworkInspectorConfig
import kotlin.time.Duration.Companion.minutes

NetworkInspector.initialize(
    application,
    NetworkInspectorConfig(
        bufferWindow = 10.minutes,
        maxBufferedEvents = 20_000,
        maxBufferedBytes = 32L * 1024 * 1024,
        modeLabel = "debug",
    ),
)