open
Boot a selected device and open an app, deep link, or URL as the automation target. Record Metro/debug hints so a later reload reuses the same session binding.
Instructions
Boot the selected device when needed, then open an app, deep link, or URL in a session. Use the app or URL inputs to choose what becomes the foreground automation target. Metro and debug runtime hints given here are recorded as the session's dev-server binding, so a later reload reuses them; a fresh open without them clears any binding left by a previous same-name session.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app | No | App name, bundle id, package, or URL. | |
| cwd | No | Working directory for command execution. | |
| url | No | Optional URL passed with an app shell. | |
| udid | No | iOS device UDID selector. | |
| debug | No | Enable debug diagnostics. | |
| force | No | Overwrite an existing --save-script target instead of refusing (alias: --overwrite). | |
| runId | No | Lease run identifier. | |
| device | No | Device name selector. | |
| serial | No | Android device or Vega VVD serial selector. | |
| target | No | Alias for deviceTarget on commands without a UI target field. Interaction commands reserve target for the UI element. | |
| tenant | No | Remote tenant identifier. | |
| leaseId | No | Existing lease identifier. | |
| session | No | Agent-device session name. | |
| surface | No | macOS presentation surface to open: the app itself, the frontmost app, the desktop, or the menu bar. | |
| testIme | No | Activate the headless Android test IME for deterministic Unicode text entry (default on for emulators; opt-in on real devices). | |
| activity | No | Android activity name. | |
| noRecord | No | Do not record this action. | |
| platform | No | Platform selector used to resolve a device. | |
| relaunch | No | Force relaunch. | |
| stateDir | No | Agent-device state directory. | |
| bundleUrl | No | Session-scoped bundle URL hint applied to the opened app. | |
| deviceHub | No | Use Xcode Device Hub when surfacing Apple simulators. | |
| launchUrl | No | Session-scoped launch URL hint applied to the opened app. | |
| metroHost | No | Session-scoped Metro/debug host hint applied to the opened app. | |
| metroPort | No | Session-scoped Metro/debug port hint applied to the opened app. On an emulator/simulator the host defaults to the loopback alias (Android 10.0.2.2, iOS 127.0.0.1) when --metro-host is omitted; physical devices still require an explicit --metro-host. | |
| foreground | No | [RFC prototype] On a fresh session with no app argument, resolve the target from the sole booted iOS simulator's sole running app and include an initial interactive snapshot in the response. Fails with AMBIGUOUS_MATCH when the environment is not unambiguous (0 or 2+ booted simulators, or no confidently-detectable running app) — never guesses. | |
| launchArgs | No | Launch arguments forwarded verbatim to the platform launch command. | |
| saveScript | No | ||
| includeCost | No | Include per-command agent-cost (cost.wallClockMs, …) in structuredContent. Defaults to off; the default response shape is unchanged. | |
| deviceTarget | No | Device target form. Maps to the CLI --target flag. | |
| daemonBaseUrl | No | Remote daemon base URL. | |
| launchConsole | No | Launch console mode. | |
| responseLevel | No | Response verbosity: token-cheap digest / default (today) / full. Defaults to default; the default response shape is unchanged. | |
| daemonAuthToken | No | Remote daemon auth token. | |
| iosXctestEnvDir | No | Writable directory for iOS XCTest runner env overlays. | |
| mcpOutputFormat | No | MCP text content format. Defaults to optimized agent-friendly text; use json for JSON text. Structured content is always returned separately. | |
| iosXctestrunFile | No | Externally built iOS XCTest runner .xctestrun artifact path. | |
| iosSimulatorDeviceSet | No | iOS simulator device-set path used for device resolution. | |
| androidDeviceAllowlist | No | Android serial allowlist used for device resolution. | |
| iosXctestDerivedDataPath | No | Derived data path for external iOS XCTest runner execution. |