Features

Everything you need to inspect your app's network traffic — without leaving the device.

Requirements

Ferret requires Ktor as your HTTP client. Here are the full version requirements before adding the dependency.

iOS targets

Ferret publishes pre-built artifacts for all three standard iOS targets:

• iosArm64 — physical iPhone / iPad devices
• iosSimulatorArm64 — Apple Silicon simulators
• iosX64 — Intel Mac simulators

Basic Integration

Add the dependency from Maven Central and install the Ktor plugin — that's all it takes.

Step 1 — Version catalog

Declare the version and library alias in gradle/libs.versions.toml:

[versions]
ferret = "1.0.0"

[libraries]
ferret = { module = "io.github.ferret-org:ferret", version.ref = "ferret" }

Step 2 — Add the dependency

In your shared/common module's build.gradle.kts:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.ferret)
        }
    }
}

Android Setup

Full setup guide for Android: manifest permissions, client configuration, and what Ferret configures automatically on first run.

1 · Add manifest permissions

Add both permissions to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

2 · Install the plugin

import com.ferret.intercept.Ferret
import com.ferret.intercept.install
import io.ktor.client.*
import io.ktor.client.engine.okhttp.*

val client = HttpClient(OkHttp) {
    install(Ferret) {
        context = applicationContext
    }
}

Pass an Android Context to the context property. Using applicationContext is recommended — it survives configuration changes and Activity recreation.

3 · What Ferret configures automatically

The first time the plugin initializes it performs four setup steps automatically:

1. Creates its Room database on-device to persist captured network records.
2. Creates a notification channel ("General" by default) on Android 8+.
3. Registers a dynamic launcher shortcut labeled "Open Ferret Inspector".
4. Starts posting the rolling notification as traffic flows through the client.

Activity auto-merge

Ferret's inspector activity (com.ferret.ui.FerretActivity) is declared in the library's own manifest and merges into your app automatically at build time. No manual declaration in your manifest is needed.

iOS Setup

Ferret works on iOS with minimal setup. No context property, no manifest changes — install the plugin and decide how to present the inspector.

Install the plugin

import com.ferret.intercept.Ferret
import com.ferret.intercept.install
import io.ktor.client.*
import io.ktor.client.engine.darwin.*

val client = HttpClient(Darwin) {
    install(Ferret) {}
}

There is no context field on iOS. Ferret initializes automatically the first time the plugin is installed.

Presenting the inspector

iOS has no equivalent of Android's home-screen app shortcuts, so you decide where and how to surface the inspector. Common approaches:

• A debug section in your app's settings screen
• A shake gesture (override motionEnded in your root view controller)
• A hidden tap sequence on a logo or version label
• A long-press on a designated debug element

To open the inspector, call FerretIosUi.open() from Kotlin or present ferretViewController() from Swift:

FerretIosUi.open()

let vc = YourSharedFramework.ferretViewController()
present(vc, animated: true)

Notifications on iOS

Ferret uses UNUserNotificationCenter on iOS. To have Ferret request notification permission at startup, set requestPermission = true:

install(Ferret) {
    configuration = FerretConfiguration(
        notifications = NotificationConfiguration(
            requestPermission = true
        )
    )
}

Opening the Inspector

Several ways to open the Ferret inspector UI, depending on your platform and workflow.

Android Android

Notification tap

While Ferret is capturing traffic it posts a rolling system notification. Tapping it opens FerretActivity directly — no setup required beyond installing the plugin.

Home-screen shortcut

Ferret registers a dynamic launcher shortcut labeled "Open Ferret Inspector". Long-press your app's icon and select it to jump into the inspector at any time, even if the notification is dismissed.

Programmatic launch

Launch from a debug settings screen, a hidden gesture, or any other trigger:

startActivity(
    Intent(context, Class.forName("com.ferret.ui.FerretActivity"))
)

iOS iOS

Notification tap

When Ferret is active and has notification permission, it posts a rolling notification via UNUserNotificationCenter. Tapping it opens the inspector directly — no extra code needed. Make sure requestPermission = true is set in NotificationConfiguration, or request the permission yourself before Ferret can show the notification.

From Kotlin / shared code

FerretIosUi.open()

From Swift

// Replace "YourSharedFramework" with your actual Kotlin/Native framework name
let controller = YourSharedFramework.ferretViewController()
present(controller, animated: true)

Ferret Configuration

All of Ferret's behavior is controlled through a single FerretConfiguration data class. Pass it to install(Ferret) { configuration = ... }. If omitted, defaults are used.

Full example

install(Ferret) {
    context = applicationContext          // Android only
    configuration = FerretConfiguration(
        notifications = NotificationConfiguration(
            maxBufferSize       = 5,
            defaultPriority     = NotificationPriority.HIGH,
            defaultChannel      = NotificationChannelSpec(
                id   = "ferret_debug",
                name = "Ferret Debug"
            ),
            defaultSmallIcon    = R.drawable.ic_notification, // Android only
            requestPermission   = false
        ),
        retentionDurationHours = 24L
    )
}

FerretConfiguration properties

Retention

Ferret automatically purges records older than retentionDurationHours each time the plugin initializes. The default (12 hours) is enough for a typical development session while bounding on-device storage use. Increase it if you need to retain history across multiple app launches.

Notification Settings

Control how the rolling capture notification looks and behaves using NotificationConfiguration.

NotificationConfiguration properties

NotificationPriority

Maps to NotificationCompat priority constants on Android and UNNotificationInterruptionLevel on iOS.

NotificationChannelSpec

Defines the Android notification channel. Channels are created once — changing properties after the channel exists requires the user to clear app data or reinstall.

NotificationChannelSpec(
    id   = "ferret_debug",  // unique channel ID — used internally
    name = "Ferret Debug"   // display name shown in system notification settings
)

Notification Permission

Starting with Android 13 (API 33), apps must request POST_NOTIFICATIONS at runtime before they can display any notification.

Ferret's responsibility

Ferret declares POST_NOTIFICATIONS in its own manifest so it merges into your app, but it does not request the permission at runtime. Your app is responsible for requesting it — the same way you would for any of your own notifications.

Requesting at runtime

If your app already requests notification permission for another feature, no extra work is needed. If not, add a runtime request somewhere sensible — first launch, an onboarding screen, or a debug settings screen.

Compose API

val permissionLauncher = rememberLauncherForActivityResult(
    ActivityResultContracts.RequestPermission()
) { granted ->
    // handle the result
}

LaunchedEffect(Unit) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        permissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
    }
}

Traditional API

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    ActivityCompat.requestPermissions(
        this,
        arrayOf(Manifest.permission.POST_NOTIFICATIONS),
        REQUEST_CODE_NOTIFICATIONS
    )
}

Inspector Overview

The Ferret inspector is a full Compose Multiplatform UI shared between Android and iOS. Here's a tour of what it offers.

Network record list

The main screen shows every captured HTTP call and WebSocket event, newest first. Each row shows:

• HTTP method badge (GET, POST, …) or a WebSocket indicator
• Request URL / path
• Response status code, color-coded by range (2xx green, 4xx orange, 5xx red)
• Total request duration in milliseconds

Type tabs

Search

The search bar filters the active list by URL or path substring. Combine the tab filter with search to zero in on a specific request fast.

Detail screen — HTTP

Tap any HTTP record to open the detail view. Four tabs are available:

• Overview — method, full URL, status code, timing in ms, protocol, TLS info
• Request — all request headers and the request body
• Response — all response headers and the response body
• Timing — per-phase breakdown (DNS, connect, TLS, TTFB, transfer)

Detail screen — WebSocket

• Overview — URL, connection state, total duration
• Messages — all sent and received frames with timestamps, frame type, and byte size

Share

From the detail screen tap Share to export a request in two formats:

• cURL command — a ready-to-run shell command you can paste into a terminal or a colleague's chat
• Plain text — a human-readable summary suitable for filing a bug report

Copy to clipboard

Tap any individual field — URL, header name/value, body, status code — to copy it directly to the clipboard.

Clear history

The trash icon in the inspector toolbar wipes all captured records from the local database immediately. The inspector will accumulate new records as fresh requests are made.

FAQ

Common questions about Ferret.

Developers

Ferret is built and maintained by the following developers. Contributions, issues, and feedback are welcome on GitHub.

Aditya Gupta

Core Developer

@Aditya-gupta99

Nagarjuna

Core Developer

@Nagarjuna0033

About & License

Ferret is an open-source Kotlin Multiplatform library licensed under the Apache License 2.0.

Why Ferret?

Inspecting mobile network traffic has traditionally required external tools: Charles Proxy, Proxyman, or Wireshark — each needing SSL certificate trust profiles, Wi-Fi proxy configuration, and a desktop machine on the same network. Ferret eliminates that friction by living inside the app process with a self-contained on-device UI. Same visibility, no external dependencies.

Technology stack

Maven coordinates

License

Ferret is licensed under the Apache License 2.0.