Reference

Runtime protocol reference

Every procedure of the open runtime contract, generated from the descriptors in @alivelabs/troupe-protocol (packages/protocol). The local runtime serves them over REST, RPC and MCP; Troupe Cloud serves the same contract.

Groups

67 procedures in 15 groups; 32 are MCP tools.

Group	Purpose	Procedures	MCP tools
`runtime`	Discovery, health and administration of the runtime itself.	7	0
`pairings`	Browser access to a local runtime through origin-bound pairing.	4	0
`catalog`	What can be requested: device types and OS versions per platform.	2	2
`sessions`	Device acquisition: a session holds one device until it is released or expires.	7	6
`apps`	Install and lifecycle of apps on a session's device.	8	6
`ui`	The accessibility tree, resolved on the device: snapshots, queries and waits.	4	4
`input`	Actions. Locator and ref targets auto-wait on the runtime side.	14	11
`system`	Device settings: location, appearance, the clipboard and the status bar.	5	0
`media`	Screenshots and screen recordings.	3	1
`logs`	Device, app and driver logs, and crash reports.	3	2
`debug`	The JavaScript runtime of a React Native debug build, through its dev server (Metro): connect, and evaluate code. Experimental and local only.	2	0
`streams`	Tickets for the live video and input stream (`/v1/stream`).	1	0
`traces`	Trace chunks the runtime records for the test framework.	2	0
`files`	Downloads of files returned as a `FileRef`.	1	0
`runs`	Test-run reports a runner publishes and clients follow.	4	0

Also: shared schemas, scopes, errors.

Reading a procedure

REST is /v1/<group>/<operation-kebab>: GET with query parameters when the procedure is read-only and its input is flat, otherwise POST with a JSON body. RPC is /rpc/v2/<group>/<operation>. Send Authorization: Bearer <token> and Troupe-Contract: 1.0.
MCP: the tool name is the id with . replaced by _. Only procedures marked as tools are served on /mcp and by troupe mcp. The hints become the tool's annotations.
Auth lists the scopes a caller must hold, all of them (scopes). Tenancy says what the input names and whose view it must be in.
Requires names the capabilities the device must declare; the runtime checks them before it calls the platform and answers CAPABILITY_UNSUPPORTED otherwise.
Input is a strict object: an unknown key fails with VALIDATION. ? marks an optional field; comments give defaults and bounds. Output objects are read leniently: unknown keys are kept, and an enum written 'a' | 'b' | … is open, so a client must handle values it does not know.
Errors: the letters are the implicit sets (U universal, S session, D drive, L locator, E environment), followed by the extra codes. Every surface carries the same error body (errors).
Stability: an experimental procedure may change or disappear in any minor version and is never an MCP tool; a stable one changes only additively within its major.

All procedures

Procedure	REST	Auth	MCP tool	Stability
`runtime.version`	`GET /v1/runtime/version`	`public`	—	stable
`runtime.capabilities`	`GET /v1/runtime/capabilities`	`session`	—	stable
`runtime.status`	`GET /v1/runtime/status`	`runtime:read`	—	stable
`runtime.hostInfo`	`GET /v1/runtime/host-info`	`runtime:read`	—	stable
`runtime.doctor`	`GET /v1/runtime/doctor`	`runtime:read`	—	stable
`runtime.shutdown`	`POST /v1/runtime/shutdown`	`runtime:admin`	—	stable
`runtime.sweep`	`POST /v1/runtime/sweep`	`runtime:admin`	—	stable
`pairings.create`	`POST /v1/pairings/create`	`runtime:admin`	—	experimental
`pairings.redeem`	`POST /v1/pairings/redeem`	`public`	—	experimental
`pairings.list`	`GET /v1/pairings/list`	`runtime:admin`	—	experimental
`pairings.revoke`	`POST /v1/pairings/revoke`	`runtime:admin`	—	experimental
`catalog.deviceTypes`	`GET /v1/catalog/device-types`	`devices:read`	`catalog_deviceTypes`	stable
`catalog.osVersions`	`GET /v1/catalog/os-versions`	`devices:read`	`catalog_osVersions`	stable
`sessions.create`	`POST /v1/sessions/create`	`devices:acquire`	`sessions_create`	stable
`sessions.get`	`GET /v1/sessions/get`	`devices:read`	`sessions_get`	stable
`sessions.list`	`GET /v1/sessions/list`	`devices:read`	`sessions_list`	stable
`sessions.wait`	`GET /v1/sessions/wait`	`devices:read`	`sessions_wait`	stable
`sessions.heartbeat`	`POST /v1/sessions/heartbeat`	`devices:acquire`	`sessions_heartbeat`	stable
`sessions.release`	`POST /v1/sessions/release`	`devices:acquire`	`sessions_release`	stable
`sessions.events`	`GET /v1/sessions/events`	`devices:read`	—	stable
`apps.install`	`POST /v1/apps/install`	`apps:install`	`apps_install`	stable
`apps.uninstall`	`POST /v1/apps/uninstall`	`apps:install`	—	stable
`apps.launch`	`POST /v1/apps/launch`	`devices:drive`	`apps_launch`	stable
`apps.terminate`	`POST /v1/apps/terminate`	`devices:drive`	`apps_terminate`	stable
`apps.list`	`GET /v1/apps/list`	`devices:read`	`apps_list`	stable
`apps.clearData`	`POST /v1/apps/clear-data`	`apps:install`	`apps_clearData`	stable
`apps.openUrl`	`POST /v1/apps/open-url`	`devices:drive`	`apps_openUrl`	stable
`apps.setPermissions`	`POST /v1/apps/set-permissions`	`apps:install`	—	stable
`ui.snapshot`	`GET /v1/ui/snapshot`	`devices:read`	`ui_snapshot`	stable
`ui.query`	`POST /v1/ui/query`	`devices:read`	`ui_query`	stable
`ui.waitFor`	`POST /v1/ui/wait-for`	`devices:read`	`ui_waitFor`	stable
`ui.describeAt`	`GET /v1/ui/describe-at`	`devices:read`	`ui_describeAt`	stable
`input.tap`	`POST /v1/input/tap`	`devices:drive`	`input_tap`	stable
`input.doubleTap`	`POST /v1/input/double-tap`	`devices:drive`	`input_doubleTap`	stable
`input.longPress`	`POST /v1/input/long-press`	`devices:drive`	`input_longPress`	stable
`input.swipe`	`POST /v1/input/swipe`	`devices:drive`	`input_swipe`	stable
`input.drag`	`POST /v1/input/drag`	`devices:drive`	—	stable
`input.pinch`	`POST /v1/input/pinch`	`devices:drive`	—	stable
`input.type`	`POST /v1/input/type`	`devices:drive`	`input_type`	stable
`input.fill`	`POST /v1/input/fill`	`devices:drive`	`input_fill`	stable
`input.pressKey`	`POST /v1/input/press-key`	`devices:drive`	`input_pressKey`	stable
`input.pressButton`	`POST /v1/input/press-button`	`devices:drive`	`input_pressButton`	stable
`input.scroll`	`POST /v1/input/scroll`	`devices:drive`	`input_scroll`	stable
`input.setOrientation`	`POST /v1/input/set-orientation`	`devices:drive`	`input_setOrientation`	stable
`input.gesture`	`POST /v1/input/gesture`	`devices:drive`	—	stable
`input.hideKeyboard`	`POST /v1/input/hide-keyboard`	`devices:drive`	`input_hideKeyboard`	stable
`system.setLocation`	`POST /v1/system/set-location`	`devices:drive`	—	experimental
`system.setAppearance`	`POST /v1/system/set-appearance`	`devices:drive`	—	experimental
`system.getClipboard`	`GET /v1/system/get-clipboard`	`devices:drive`	—	experimental
`system.setClipboard`	`POST /v1/system/set-clipboard`	`devices:drive`	—	experimental
`system.setStatusBar`	`POST /v1/system/set-status-bar`	`devices:drive`	—	experimental
`media.screenshot`	`POST /v1/media/screenshot`	`devices:read`	`media_screenshot`	stable
`media.startRecording`	`POST /v1/media/start-recording`	`devices:read`	—	stable
`media.stopRecording`	`POST /v1/media/stop-recording`	`devices:read`	—	stable
`logs.stream`	`GET /v1/logs/stream`	`logs:read`	—	stable
`logs.read`	`GET /v1/logs/read`	`logs:read`	`logs_read`	stable
`logs.crashes`	`GET /v1/logs/crashes`	`logs:read`	`logs_crashes`	stable
`debug.connect`	`POST /v1/debug/connect`	`devices:drive`	—	experimental
`debug.evaluate`	`POST /v1/debug/evaluate`	`devices:drive`, `apps:debug`	—	experimental
`streams.ticket`	`POST /v1/streams/ticket`	`devices:read`	—	stable
`traces.startChunk`	`POST /v1/traces/start-chunk`	`devices:read`	—	stable
`traces.stopChunk`	`POST /v1/traces/stop-chunk`	`devices:read`	—	stable
`files.get`	`GET /v1/files/get`	`devices:read`	—	stable
`runs.publish`	`POST /v1/runs/publish`	`runs:report`	—	experimental
`runs.list`	`GET /v1/runs/list`	`runs:read`	—	experimental
`runs.get`	`GET /v1/runs/get`	`runs:read`	—	experimental
`runs.events`	`GET /v1/runs/events`	`runs:read`	—	experimental