Docs Operation reference runtime operations
runtime operations#
8 operations. Generated from assets/operations.json; all areas.
On this page (8)
runtime.start#
Connect native runtime
Start or reuse the single native display session for this device. Repeated calls return its existing session ID. Supports Android, physical iPhone from Linux, and Apple Simulator on an optional SSH Mac.
Annotations: writes, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
platform | string | yes | one of android, ios | |
device | string | yes | non-empty, up to 200 characters | |
remote | string | Optional configured Mac workspace for an Apple Simulator; omit for a physical iPhone on Linux. | ||
server | string | Optional scrcpy 4.1 server JAR override. | ||
fps | integer | 60 | 1 to 60 | |
bit_rate | integer | 12000000 | 100000 to 50000000 | |
runner_bundle_id | string | "" | Installed WebDriverAgent runner identifier for a physical iPhone. | |
runner_mode | string | "xctest" | one of xctest, external; xctest: start the signed WDA runner through go-ios; external: WDA is already running on the selected USB device. | |
audio | boolean | true | Forward Android output audio to this computer using a session-owned scrcpy playback job. Does not capture a microphone. Unsupported audio leaves video connected and reports audio failure. |
tomaccoctl call runtime.start '{"platform":"android","device":"<device>"}'
runtime.list#
Native sessions
List native display sessions and connection status.
Annotations: read-only, idempotent, open world.
Takes no arguments.
tomaccoctl call runtime.list
runtime.audio#
Stream device audio
Start, stop or inspect Android output audio playback on this computer without restarting the app or display session. Repeated starts reuse one playback job. Stops restore the device audio route; they do not mute the device itself. Requires Android 11+ and scrcpy.
Annotations: writes, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | yes | Connected Android runtime session ID. | |
action | string | "status" | one of start, stop, status |
tomaccoctl call runtime.audio '{"session":"<session>"}'
runtime.state#
Runtime status
Read actual runtime dimensions, video counters and transport errors.
Annotations: read-only, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | yes | matching ^[a-f0-9]{32}$; ID returned by runtime.start; separate from desktop preview sessions. |
tomaccoctl call runtime.state '{"session":"<session>"}'
runtime.stop#
Disconnect runtime
Stop this display session and its private transport. The device and application remain running.
Annotations: writes, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | yes | matching ^[a-f0-9]{32}$; ID returned by runtime.start; separate from desktop preview sessions. |
tomaccoctl call runtime.stop '{"session":"<session>"}'
runtime.input#
Native input
Deliver native input using normalized 0..1 coordinates. Android supports touch/tap/swipe/key/text/rotate; text pastes UTF-8. Physical iPhone uses WDA for Unicode text/fill, tap/swipe/rotate and gestures committed on touch-up; pinch/shake/hinge are unsupported there. Apple Simulator supports ASCII HID text and Unicode accessible fill; extra gestures depend on the companion. Pass decoded width/height after Simulator rotation.
Annotations: writes, not idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | yes | matching ^[a-f0-9]{32}$; ID returned by runtime.start; separate from desktop preview sessions. | |
action | string | yes | one of touch, tap, swipe, key, text, fill, rotate, shake, pinch, hinge | |
phase | string | one of down, move, up, cancel | ||
x | number | 0 to 1 | ||
y | number | 0 to 1 | ||
x2 | number | 0 to 1 | ||
y2 | number | 0 to 1 | ||
duration | number | 0.3 | 0.01 to 5 | |
key | string | one of home, back, escape, enter, backspace, delete, tab, up, down, left, right, power, volume_up, volume_down, apps | ||
text | string | up to 16000 characters | ||
orientation | string | one of portrait, portrait_upside_down, landscape_left, landscape_right | ||
scale | number | 0.05 to 20 | ||
angle | number | 0 to 180 | ||
width | integer | 1 to 16384 | ||
height | integer | 1 to 16384 |
tomaccoctl call runtime.input '{"session":"<session>","action":"touch"}'
runtime.capture#
Native capture
Capture a full-resolution PNG from the actual runtime to a local path.
Annotations: writes, not idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | yes | matching ^[a-f0-9]{32}$; ID returned by runtime.start; separate from desktop preview sessions. | |
path | string | yes | non-empty |
tomaccoctl call runtime.capture '{"session":"<session>","path":"<path>"}'
runtime.hierarchy#
Native accessibility tree
Read Android UI XML, the physical iPhone WDA XML hierarchy or the iOS Simulator accessibility tree for agent inspection.
Annotations: read-only, idempotent, open world.
| Argument | Type | Required | Default | Details |
|---|---|---|---|---|
session | string | yes | matching ^[a-f0-9]{32}$; ID returned by runtime.start; separate from desktop preview sessions. |
tomaccoctl call runtime.hierarchy '{"session":"<session>"}'