FridaBox/docs/USAGE.md

Usage

FridaBox keeps every imported application inside its private virtual workspace. Importing an APK does not install that package into Android's real PackageManager.

Import an application

1. Open Workspace and tap Import APK.
2. Select one ARM64 base .apk through Android's document picker.
3. FridaBox validates the APK, records its SHA-256, and creates a private guest.

Split-only packages (.apks, .xapk, and .apkm) and unsupported native ABIs are rejected.

Choose a launch mode

Every guest remembers one of three independent modes:

• On-device: select a trusted .js file once. FridaBox stores a byte-for-byte private copy, records its SHA-256, and loads it through Frida Gadget's Script interaction before the guest Application starts. No cable, computer, Frida CLI, port forwarding, or controller process is required on later launches.

• Computer: starts the loopback-only Gadget listener and pauses before the guest Application. Attach through the normal Frida workflow, for example:

  frida -U gadget -l path/to/agent.js
  

• Clean: recycles the virtual process and launches without loading Frida Gadget. The selected on-device agent is retained for future use.

Switching modes always stops the previous guest process before the next launch.

On-device agents

Select On-device, tap Select JavaScript, review the trust warning, and choose a .js file up to 16 MiB. The original file is not modified. The private copy and the private Gadget executable are made read-only before execution.

An autonomous script has no computer-side message handler. Calls such as send() may be intentionally unobserved, while hooks, replacements, Java calls, native interceptors, and in-app overlays continue to run in the guest process.

Runtime and management

The Runtime tab reports the latest package, process, virtual user ID, virtual process slot, source APK, ClassLoader, selected mode, state, and latest error. Use Manage on an app card for app details, runtime details, virtual data clearing, or removal from the private workspace.

Only run JavaScript agents you trust. An on-device agent executes with the same access as the virtual guest process.