Introducing a new way to review your PRs.

Read the announcement

rikkaapps / shizuku

Using system APIs directly with adb/root privileges from normal apps through a Java process started with app_process.

View on GitHub

12 documents · Updated Nov 16, 2026

docs / starter-bootstrap-flow

Starter bootstrap flow

Overview

The starter module is a minimal Android library whose runtime entry point is starter/…/ServiceStarter.java. It is launched as a privileged app_process Java main, not as an Android component: commandForUserService(...) builds a shell command that sets CLASSPATH to the manager APK, invokes the supplied appProcess binary with /system/bin as the app-process data directory, assigns a --nice-name, and runs moe.shizuku.starter.ServiceStarter with the user-service token, package, class, and caller uid.

ServiceStarter.main(...) prepares the main looper when the privileged process did not already create one, then delegates construction of the app-provided user service to rikka.shizuku.server.UserService.create(args). That API returns the service binder plus the token that must be handed back to the Shizuku manager. If service creation fails, or if the binder cannot be delivered to the manager, the process exits with status 1; otherwise it enters Looper.loop() and stays alive until the manager binder dies.

Binder handoff is done through the manager app's content provider rather than through an exported Android service. ServiceStarter.sendBinder(...) targets authority moe.shizuku.privileged.api.shizuku in user 0, obtains it with ActivityManagerApis.getContentProviderExternal(...), sends a Bundle containing moe.shizuku.privileged.api.intent.extra.BINDER as a moe.shizuku.api.BinderContainer plus ShizukuApiConstants.USER_SERVICE_ARG_TOKEN, and calls provider method sendUserService. The reply is expected to contain another BinderContainer for the Shizuku server/manager binder. ServiceStarter stores that returned binder in the static shizukuBinder field and links a death recipient that terminates the user-service process when Shizuku exits. The content-provider reference is always released with ActivityManagerApis.removeContentProviderExternal(...) in the finally block.

starter/…/IContentProviderCompat.java isolates the hidden IContentProvider.call(...) signature churn across Android releases. Android 12L/API 31+ is called with an AttributionSource built from Os.getuid(), falling back to the API 30 form if the runtime hidden API shape does not match the compile-time stub. API 30 uses (callingPkg, attributionTag, authority, method, arg, extras), API 29 uses (callingPkg, authority, method, arg, extras), and older releases use (callingPkg, method, arg, extras). ServiceStarter passes null for attribution tag and calling package because this privileged-process call only needs to reach the known Shizuku provider authority.

Build and manifest wiring are intentionally small. starter/build.gradle declares the module as an Android library with namespace rikka.shizuku.starter, disables BuildConfig, uses dev.rikka.tools.refine, and depends on :common, :shared, and :server-shared at runtime/implementation scope. It compiles against :provider, libs.hidden.stub, libs.hidden.compat, libs.refine.runtime, and AndroidX annotations so the starter can reference provider/shared binder contracts and hidden framework APIs without declaring app components. starter/…/AndroidManifest.xml is an empty <manifest />, confirming that this module contributes code for privileged process startup rather than activities, services, receivers, or providers.

Coupling

  • If ServiceStarter.USER_SERVICE_CMD_FORMAT or commandForUserService(...) in starter/…/ServiceStarter.java changes, verify the shell caller that executes the returned string still passes --token, --package, --class, and --uid exactly as rikka.shizuku.server.UserService.create(args) expects. The command currently quotes string arguments so shell metacharacters in class names or process suffixes are not expanded before the Java main sees them.
  • If the manager provider authority, method name, token key, or binder extra changes, update starter/…/ServiceStarter.java and the provider-side handler together. The starter hard-codes authority moe.shizuku.privileged.api.shizuku, method sendUserService, extra moe.shizuku.privileged.api.intent.extra.BINDER, and ShizukuApiConstants.USER_SERVICE_ARG_TOKEN; a mismatch makes the user service start successfully but fail during binder registration.
  • If hidden framework stubs or the compile SDK change, re-check starter/…/IContentProviderCompat.java against every supported Android API level. A wrong IContentProvider.call(...) overload fails at runtime in the privileged process, and ServiceStarter.sendBinder(...) treats that as startup failure.
  • If dependencies in starter/build.gradle move between implementation and compileOnly, verify both runtime loading and compile-time hidden API access. :provider and libs.hidden.stub are compile-only because the privileged process uses the manager APK CLASSPATH and platform classes at runtime, while :common, :shared, and :server-shared must be packaged with code used by ServiceStarter and UserService creation.

Risks

  • starter/…/ServiceStarter.java constructs a shell command with interpolated string values. Commit d1a71dd fixed failures where unquoted class names containing $ were expanded by the shell; removing or weakening the current quotes can break nested-class user services or process suffixes with shell-significant characters.
  • starter/…/ServiceStarter.java relies on the returned Shizuku binder staying strongly referenced in shizukuBinder. Commit 8e0e587 fixed user services sometimes not exiting after Shizuku exited by retaining that binder before linkToDeath(...); if this is changed back to a local-only reference, the death recipient can be unlinked by garbage collection and orphan the privileged process.
  • starter/…/ServiceStarter.java has a one-time recovery path for a dead content provider binder: it force-stops moe.shizuku.privileged.api, waits one second, and retries. Commit 5f5d313 added this because getContentProviderExternal(...) can return a dead provider; removing the retry can make otherwise valid user-service starts fail when the manager provider is in that state.