Run iOS simulators and Android emulators in any browser โ no toolchain setup, no device pool, no cloud uploads.
Your builds, streams, and recordings stay on infrastructure you control.
No WebDriverAgent ยท 2-line setup ยท MIT
๐ Docs ยท ๐ Quick Start ยท ๐ฅ Demo ยท ๐ฌ Setup
Streams over H.264 with a zero-buffer decoder (no MSE) โ latency measurements โ
> **v0.x, actively developed** โ backward-compatible by default; breaking changes are rare and always noted in the [changelog](CHANGELOG.md). [Roadmap โ](ROADMAP.md) --- ## Why tapflow? Mobile QA usually depends on access to simulators, emulators, or physical devices โ and that access is uneven across a team. For mobile developers it means opening Xcode or Android Studio on a Mac. For everyone else, it often means asking a mobile developer every single time: > **Backend developer** โ "How do I install the sandbox build to check what was deployed?" > > **Product manager** โ "I keep installing and removing versions just to compare behavior." > > **Designer** โ "I need to check the layout across screen sizes, but I don't have the right devices." Physical devices add their own overhead โ OS-version coverage, availability, charging, storage, handoff. Cloud simulator services solve access, but they require uploading internal builds to a third-party service and paying for remote devices while your own Macs can already run the same simulators. We hit this exact problem, so we built tapflow. | Solution | The catch | |----------|-----------| | Appetize / BrowserStack | Recurring cost โ and app builds are uploaded to a third-party cloud | | Physical devices | Cost, availability, OS coverage, management overhead | | Xcode / Android Studio | Each teammate needs a Mac and a full mobile toolchain | | **tapflow** | Reuse your own Macs โ data stays on infrastructure you control, and the whole team does QA from a browser | ## How it works tapflow connects three parts: 1. A **self-hosted relay** (Linux or Mac) โ also serves the dashboard on the same port, so there's no separate web server. 2. A **macOS agent** that drives the iOS Simulator and Android emulator โ it connects *outbound* to the relay (no inbound firewall rules) and injects iOS touch directly, without WebDriverAgent. 3. A **browser dashboard** for the rest of the team โ pick an available device and interact with it in real time while the simulators keep running on your Macs. ```text Browser (your team) โโ WebSocket โโ Relay Server โโ WebSocket (outbound) โโ Mac Agent (Linux / Mac) (iOS ยท Android) ``` ## What tapflow is not tapflow doesn't replace native mobile development tools. Mobile developers still use Xcode, Android Studio, and their build tooling. tapflow makes the *running* simulators and emulators accessible to the rest of the team through a browser, and it is not a device farm. It does include automation โ a deterministic flow runner, and an MCP server for LLM agents โ but wiring in external automation frameworks like WebDriverAgent or Appium is out of scope; tapflow ships its own minimal runner instead. Where this is heading is laid out in [VISION.md](VISION.md): three ways to use one shared layer, and work that moves from something done once to something every build runs. ## Quick Start ### 1. Install ```sh npm install -g tapflow # or: yarn global add tapflow | pnpm add -g tapflow ``` ### 2. Set up the environment On the Mac that will run an agent, install the simulator/emulator prerequisites in one step: ```sh tapflow setup ``` Skip this on a relay-only server (Linux). See [Environment Setup](https://www.tapflow.dev/operate/environment-setup) for details. ### 3. Start relay + agent ```sh tapflow start # โ Relay started on http://localhost:4000 # โ iOS Agent connected (3 simulators available) ``` This starts both the relay and the agent on the same Mac (local mode). ### 4. Create the first admin account Open `http://localhost:4000` in your browser. tapflow redirects you to `/setup` to create the admin account. > **Headless server?** Use `tapflow admin init` to create the admin account via CLI instead. ### 5. Open the dashboard Navigate to `http://localhost:4000` and sign in with the account you just created. > **Having issues?** Run `tapflow doctor` to re-check prerequisites at any time. ## Requirements | Component | Requirements | |-----------|-------------| | **Relay server** | Node.js โฅ 22, any OS (Linux/macOS), ~512 MB RAM | | **iOS Agent** | macOS 26 or 27, Xcode 26 or 27 + iOS Simulator runtime (or run `tapflow setup ios`), Node.js โฅ 22 | | **Android Agent** | macOS, Java + Android SDK with an AVD (or run `tapflow setup android`), Node.js โฅ 22 | | **Browser (QA)** | Any modern browser โ Chrome, Firefox, Safari, Edge | > Agents run on **macOS only** (they drive the iOS Simulator and Android emulator on a Mac). The relay runs anywhere. ## Features - **No mobile toolchain for QA users** โ teammates test from a browser without installing Xcode, Android Studio, or local simulator tooling. - **Self-hosted by default** โ no third-party cloud and no external accounts; everything runs on hardware you already own. - **Use your existing Mac setup** โ run agents on Macs that already have the iOS Simulator or Android emulator available. - **API-first** โ REST endpoints and Personal Access Tokens support CI/CD and AI-agent workflows. What's included: - **Browser streaming** โ iOS & Android at ~30 fps, no extra app on the device. Both stream H.264 through a 2-tier decoder (WebCodecs on secure contexts, WASM/tinyh264 on plain HTTP), which removes the media-element buffer from the decode path. Resolution adapts to the connection โ native on a secure context, downscaled on plain-HTTP LAN.[1](#latency-note) - **Codec fallback** โ the stream negotiates the codec per client and falls back to JPEG when a hardware or WASM decoder isn't available, so older browsers still work. - **Touch, swipe & pinch** โ real-time input forwarded to the simulator or emulator. - **Deeplink toolbar** โ open supported deeplinks directly from the QA toolbar. - **Keyboard shortcuts** โ trigger simulator toolbar actions from the keyboard. - **Clipboard sync** โ copy and paste between your Mac and the device, in both directions. Copying *from* the device needs the dashboard on HTTPS or localhost; over plain HTTP the text lands on the device's own clipboard and the dashboard says so. - **Device audio** โ the app's sound comes back to the browser tab. - **Network control** โ take a device off the network and put it back, to test how the app behaves offline. iOS installs a network filter once; Android needs nothing. - **App Center** โ upload `.app.zip` / `.apk` and track builds by status (Backlog / In Progress / Done / Rejected). - **Session recordings** โ record and share QA sessions, kept on the relay for ~72 hours, then purged automatically. - **Screenshot REST endpoint** โ `GET /api/v1/sessions/:sessionId/screenshot` for CI and AI agents. - **Mac resource monitoring** โ CPU & RAM per agent, to spot overloaded hosts before assigning sessions. - **Team management** โ invite links, roles (Admin / Developer / QA / Viewer), and Personal Access Tokens. - **Flow runner** โ `tapflow flow run` replays a YAML flow with condition-based waits and a JUnit report, and calls no LLM at replay time. Experimental. - **MCP Server** โ `@tapflowio/mcp-server` lets Claude Code and other LLM agents control simulators as native tools. Experimental. > 1 On a real LAN, decode-to-present measures in the low tens of milliseconds (p50 ~11โ17 ms with the WASM software decoder; faster with WebCodecs on HTTPS); end-to-end "glass-to-glass" latency adds your network's round trip on top. See the [streaming latency log](contributing/streaming-latency-log.md) for the full measurements, conditions, and known limitations. ## Security & Privacy tapflow is self-hosted by design โ build files, device streams, and session recordings stay on infrastructure you control, never sent to a third-party service. | Data | Where it stays | |------|----------------| | App binaries (`.app.zip` / `.apk`) | Relay storage | | Device streams (video ยท touch) | The relay โ browser path you host | | Session recordings | Relay storage; expire after 72h, then purged | | Account & team data | The relay's SQLite DB | | Third-party simulator cloud | Not required | - **LAN-first** โ the agent โ relay leg is internal traffic; the device stream never transits a third party. - **The relay is the trust boundary** โ it holds accounts, builds and live device control, so whoever can reach it is who you are exposing. The agent only dials out. - **Authenticated by default off-host** โ the relay accepts unauthenticated connections only from its own machine (`localhost`). Browsers reaching it from elsewhere sign in; agents on another machine present an `agent`-scope token. Traffic through a tunnel counts as off-host, even though the tunnel client runs on the relay's machine. - **PAT + roles** โ Personal Access Tokens carry scopes (`builds:write` for CI uploads, `agent` for remote agents), and team roles (Admin / Developer / QA / Viewer) govern dashboard access. Found a vulnerability? See [SECURITY.md](SECURITY.md). For the full model, read [Security & Privacy](https://www.tapflow.dev/reference/security). ## Self-Hosting A single Mac needs nothing beyond `tapflow start` (see [Quick Start](#quick-start)). For a team, run the relay on a separate Linux server or dedicated Mac, and point each Mac agent at it. **Relay server:** ```sh # Recommended: PM2 for automatic restarts npm install -g pm2 tapflow JWT_SECRET=$(openssl rand -hex 32) pm2 start tapflow --name relay -- relay start pm2 save && pm2 startup ``` **Or run the relay with Docker:** ```sh docker run -d -p 4000:4000 -v "$PWD/data:/app/.tapflow/data" tapflow/tapflow:latest ``` > The image is the relay only โ agents stay on your Macs. The volume is required (it holds the sign-in secret), and invite links need `TAPFLOW_RELAY_URL`. See [Docker Compose](https://www.tapflow.dev/operate/docker) for the full setup. **Each Mac agent:** ```sh tapflow agent start --relay wss://your-relay-url --token