Getting started

Priv Kit targets Android API 26 and later. It gives one application the primitives to start, connect to, and use its own Privileged Server. Applications can use the built-in file proxy, build privileged operations directly on Binder, or define their own UserService contracts.

Add the dependencies

Start with priv-ui. It provides the Compose authorization page and exposes priv-core transitively, so the application can use the runtime, file proxy, Binder, and UserService APIs without declaring both modules.

dependencies {
    implementation("io.github.priv-kit:priv-ui:<version>")
}

Choose priv-core directly for an application-owned authorization interface:

dependencies {
    implementation("io.github.priv-kit:priv-core:<version>")
}

Configure native library packaging

Apps that support Android versions below 10 must set useLegacyPackaging to true:

android {
    packaging {
        jniLibs {
            useLegacyPackaging = true
        }
    }
}

Android 10 and later have no such restriction. Priv Kit uses the startup command that matches the value of useLegacyPackaging.

For example, on an arm64 device:

useLegacyPackaging = true:

adb shell /data/app/.../lib/arm64/libprivkitstarter.so

useLegacyPackaging = false:

adb shell /system/bin/linker64 '/data/app/.../base.apk!/lib/arm64-v8a/libprivkitstarter.so'

Configure hidden API access

Configure HiddenApiBypass in the host app:

class App : Application() {
    override fun attachBaseContext(base: Context?) {
        super.attachBaseContext(base)
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
            HiddenApiBypass.addHiddenApiExemptions("L")
        }
    }
}

Embed Privilege UI

Place PrivilegeScaffold in the app's Compose content:

PrivilegeScaffold()

The default configuration presents Root, ADB, and Manual startup. The ADB surface handles status polling, Wireless Debugging pairing, foreground permission requests, TCP/IP confirmation, and startup. Read the Privilege UI guide for configuration and silent replay.

Build a custom interface with priv-core

Use priv-core directly when the application needs to replace the supplied authorization interface. The host then owns permission prompts, pairing input, confirmation surfaces, status polling, and error presentation.

The shortest Root and Wireless Debugging calls are:

val rootServer = Privilege.startRoot()
val adbServer = Privilege.startAdb()

Both are suspend APIs. Cancelling the owning coroutine closes the active process, socket, or discovery session. See startup methods for the complete priv-core flows.

Choose a usage mode

• Use Binder for explicit raw Binder access.
• Use the file proxy for basic absolute-path file access without defining a UserService.
• Use commands for a bounded non-interactive process with streaming or captured output.
• Use UserService for an app-defined AIDL service.
• Use Privilege UI for the supplied authorization page.
• Read startup methods before replacing that page with a custom priv-core integration.

Active development

Use the version published for the release you target. The repository currently defines priv-core and priv-ui as the supported integration surface; other bytecode visibility is an implementation detail.