Runtime

Troupe Studio

Troupe Studio is a web app that the runtime serves for watching and driving devices. In it you start sessions, use a device with your mouse and keyboard, inspect its accessibility tree and read its logs.

Open it

bunx troupe studio

http://127.0.0.1:<port>/#otc=<code>

Open the URL in a browser on the same machine within a minute. The command starts the runtime daemon when none runs. It prints the URL and does not launch a browser.

The browser must support WebCodecs and decode H.264: iOS and Android devices stream H.264 only. The page works only when the runtime serves it: it cannot be opened from a file.

Pairing

The part after #otc= is a one-time pairing code. It pairs this browser tab with your runtime:

1. The page removes the code from the address bar, so it does not stay in your history.
2. It trades the code for a token that works only from the studio's own origin.
3. It keeps the token in the tab's sessionStorage. A reload keeps working; closing the tab forgets it.

The code works once and expires after a minute. The token lasts 12 hours. When the daemon restarts or the token expires, the page asks you to pair again: run troupe studio again and open the new URL, or paste the new code into the page. Unpair in the top bar forgets the token.

A paired tab may read, acquire and drive devices and read logs. It may not install apps or administer the runtime. To put an app on a device you watch in the studio, install it from a test run, the client or MCP.

The window

The top bar says Disconnected, with a banner, while the runtime does not answer, and picks up again when it does. The theme follows the system by default; the toggle cycles system, light and dark and is remembered.

Start a session

New opens a form with the platforms this runtime offers and, for the chosen platform, its device types and OS versions. Creating the session boots the device. The studio holds the session as a client, so it ends after 10 minutes without activity. See Sessions.

Sessions that other callers hold appear in the list too: a troupe test worker's device, or one an MCP agent started.

Watch and drive a device

Select a session. The device's screen appears as soon as the stream opens, which is before the session is ready while a simulator's driver is still starting.

• Pointer. Click to tap, drag to swipe, scroll with the wheel or trackpad. Hold Alt and drag to pinch.
• Keyboard. Click the screen to give it focus, then type. Paste inserts text. Shift+Escape leaves the device view, because Tab and Escape go to the device.
• Toolbar. The buttons the device's live input offers: Back, Home and the app switcher, Rotate left and right, Lock or Power, and Volume down and up. An iOS Simulator offers Home, Lock, the volume buttons and Rotate. An Android Emulator offers all of them.
• Screenshot. Saves the picture as a PNG.

One viewer drives a session at a time. The first tab that opens a session drives it; another tab shows Take control, and taking it turns the first into a watcher.

Three cases are view-only:

• A session held by troupe test. The test holds the device, and Take control is refused.
• A device whose live input is down. The status line says Input unavailable with the reason.
• A Mac Catalyst session has no stream at all: the app's window is on your desktop instead.

The inspector

The Inspector tab shows the screen's accessibility tree, one line per element, in the same form as an aria snapshot:

- application "Shop" [ref=e1]:
  - toolbar "Cart" [ref=e2]:
    - button "Back" [ref=e3]
    - heading "Cart" [level=1] [ref=e4]
  - textbox "Email" [testId="email"] [ref=e5]: "a@b.co"

• Hover a line to outline that element on the device.
• Select a line to see its properties and a suggested locator: by test id when the element has one, else by role and name, else by text.
• Filter the tree by role, name or test id, include hidden elements, or copy the whole snapshot.

The tree is read again after you drive the device. It is available once the session is ready. Locators explains how to use what you find here in a test.

Logs and session details

The Logs tab follows the device's logs live. Filter by text and by lowest level. A marker shows where lines were dropped.

The Session tab lists the session's id, status, device type, OS version and build, screen size, locale, holder, deadlines and installed apps.

Troupe Cloud

The studio can also show devices that run in Troupe Cloud. The page may reach only the addresses its runtime allows, so name the cloud when you start the daemon:

TROUPE_STUDIO_CLOUDS="https://api.troupe.ali.ve wss://<stream host>" bunx troupe studio

The list takes the cloud's API address and, as a wss:// entry, the origin of the stream url that streams.ticket returns for your sessions. If a daemon already runs, stop it first with troupe runtime stop, so that the new one gets the variable.

Then choose Troupe Cloud in the top bar, enter the cloud's address and sign in. The cloud's consent page names the address the sign-in returns to: approve only when it matches the studio's address bar. You pick one project there, and the tab then reaches that project's sessions only. Switch project signs in again, and Sign out ends the sign-in. The sign-in stays in the tab and lasts at most 12 hours.

Hosted device sessions covers the cloud's side.

Next

• Sessions: what the studio creates and how it ends
• The React components: the studio's parts, for your own page
• The live stream: how the picture and the input travel