app_launch

This tool on every surface: CLI · MCP · Python · JavaScript · Go · Java · .NET

Bring an app to the foreground, starting it if it is not running. Refs from the previous screen are discarded, so call app_map afterwards.

Changes the device, the app or the session: readOnlyHint is false.

Arguments

Name	Type	Required	What it is
app	string	yes	Package name on Android ("com.example.shop") or bundle id on iOS ("com.example.Shop").
device	string		Device serial to target, e.g. "emulator-5554". Omit when only one device is running.
driver	string: uiautomator2, uiautomator, wda		Driver to use: "uiautomator2" (default for Android; fast, installs a server APK on first use), "uiautomator" (Android, installs nothing, slower, cannot type), or "wda" (WebDriverAgent: iOS simulators and iPhones).
gray_box	boolean		Launch the app with Mobium's gray-box library turned on (on iOS the -MobiumGrayBox launch argument; on Android the MobiumGrayBox intent extra, the app started afresh), so the app says in the device log when it is busy and every action waits for it to be idle before finding its target — work the screen does not show included. Needs an app built with the library; one without it launches normally and the result says it did not answer. Not with hit_test.
hit_test	boolean		iOS simulator only: load the hit probe into the app as it launches, so every action on an element in it — tap, long press, check — first asks UIKit where the touch goes, in under a millisecond, and is refused as app_hit_test refuses when it would land elsewhere, an overlay hidden from accessibility included. Kept for the session's own relaunches of the app, for a language or a time zone. A real iPhone refuses: the probe would have to listen on its network; call app_hit_test there instead.

Examples

Each is the arguments of a tools/call request; the first is shown whole.

Bring an app to the front

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "app_launch",
    "arguments": {
      "app": "com.android.settings"
    }
  }
}

On an Android 15 emulator the answer's text was:

launched com.android.settings

mobium launch com.android.settings on an Android 15 emulator

Launch an app with the gray box on, so every action waits for it to be idle

{
  "app": "dev.mobium.mobiumapp",
  "gray_box": true
}

On an Android 15 emulator the answer's text was:

launched dev.mobium.mobiumapp, with the gray box: every action waits for the app to say it is idle