Start

Troupe documentation

Troupe boots and drives mobile devices, and tests apps on them. This page says what Troupe is made of, where it runs, and where each part is documented.

What Troupe does

Troupe's runtime starts iOS Simulators and Android Emulators, installs your .app or .apk, streams the screen, takes input, reads the accessibility tree, and collects screenshots, logs and crashes. Every one of those operations is a procedure in one contract, served over REST, RPC and MCP.

A test framework with Playwright's API runs on top of the runtime: test() and expect(), locators that wait, assertions that retry, fixtures, projects, parallel workers, traces and an HTML report.

TypeScript

import { expect, test } from '@alivelabs/troupe'

test('signs in', async ({ screen }) => {
  await screen.getByLabel('Email').fill('a@b.co')
  await screen.getByRole('button', { name: 'Sign in' }).tap()
  await expect(screen.getByRole('heading', { name: 'Welcome back' })).toBeVisible()
})

All of this runs on your own Mac with no account. Troupe Cloud runs the same runtime as a hosted service and adds accounts, hosted devices and builds.

What is in the box

Part	What it is	Read
Runtime	A daemon on your machine that owns the devices. It serves REST, RPC, MCP and the live stream on one loopback port	Runtime
Test framework	`@alivelabs/troupe`: `test`, `expect`, locators, fixtures, reporters and traces, run by Bun	Testing
CLI	The `troupe` command, in the same package: `init`, `install`, `test`, `doctor`, `studio`, `mcp` and more	CLI
Client	`@alivelabs/troupe-client`: typed calls to a runtime and the stream client, for a browser page or a Bun program	Client
React components	`@alivelabs/troupe-react`: `DeviceScreen` (a live device you can drive), a session list, an accessibility inspector and logs	React
Studio	A web app the runtime serves for watching and driving a device. `troupe studio` prints its address	Studio
MCP	The runtime's device operations as tools for a coding agent: 31 curated tools, over stdio with `troupe mcp`	MCP
Troupe Cloud	The hosted service: organizations, projects, API keys, hosted device sessions and builds	Troupe Cloud

Platforms

A platform is a kind of device the runtime can start. A config names one in use.platform.

Platform	Id	Config alias	What it runs
iOS Simulator	`ios-simulator`	`ios`	A simulator `.app`, or a `.tar.gz`, `.tgz`, `.zip` or `.ipa` holding one
Android Emulator	`android-emulator`	`android`	An `.apk`
Mac Catalyst	`catalyst`	none	A prebuilt Catalyst app that links Troupe's host

Each platform declares what it can do. Mac Catalyst has no touch input and no live stream, so some actions are refused there; the platform pages list the differences. Building a Catalyst app from an Expo source is not available. Real devices are not supported.

Hosts

Troupe runs on macOS on Apple silicon. That host runs all three platforms. Linux x86-64 with KVM is planned for Android. Intel Macs and Windows are not supported.

The troupe command is run by Bun 1.4.3 or newer. Install lists what each platform needs.