Self-hosted iOS & Android simulator streaming for QA teams

Run simulators in the browser — no Appetize, no BrowserStack, no monthly fees.
App data never leaves your network.

alpha: tapflow is in active development (v0.x). Breaking changes may appear in minor versions until v1.0.0. See ROADMAP for known gaps.

---

Demo

tapflow-clip-final-compressed.mp4

---

Why tapflow?

Solution	Problem
Appetize / BrowserStack	Expensive — app data leaves your network
Physical devices	Cost, loss, management overhead
Xcode / Android Studio	Every QA member needs their own Mac + full toolchain setup
tapflow	Use the Mac you already own — data stays on-prem, QA team uses a browser

Features

• Browser-based — QA team needs no installation. Any modern browser works.
• iOS Simulator — JPEG frame streaming at ~30 fps via SimulatorKit IOSurface. No WebDriverAgent required.
• Android Emulator — H.264 streaming via scrcpy at ~30 fps.
• Touch, swipe & pinch — real-time input forwarded to the simulator.
• App Center — upload .app.zip (iOS) or .apk (Android), manage builds by status (Backlog / In Progress / Done / Rejected).
• Session Recordings — record QA sessions, share with your team. Retained for 72 hours.
• Mac Resources — CPU & RAM monitoring per agent. Spot overloaded hosts before assigning sessions.
• Team management — invite links, roles (Admin / Developer / QA / Viewer), Personal Access Tokens for CI/CD.
• Self-hosted — deploy anywhere. No cloud dependency.

How it works

Browser (QA team)  ←─ WebSocket ─→  Relay Server  ←─ WebSocket (outbound) ─→  Mac Agent
                                  (Linux / Mac)                           (iOS · Android)

1. The Mac Agent connects outbound to the relay — no inbound firewall rules needed.
2. QA opens the dashboard in any browser and sees all available devices.
3. Touch events are forwarded in real time; the screen streams back to the browser.
4. The relay also serves the dashboard SPA on the same port — no separate web server needed.

Quick Start

1. Install

npm install -g tapflow
# or: yarn global add tapflow  |  pnpm add -g tapflow

2. Start relay + agent

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).

3. Create the first admin account

tapflow init
# ? Admin email: admin@yourteam.com
# ? Password: ********
# ✓ Admin account created

4. Open the dashboard

Navigate to http://localhost:4000 and sign in with the account you just created.

Having issues? Run tapflow doctor to auto-diagnose Node.js, Xcode, adb, and other prerequisites.

Requirements

Component	Requirements
Relay server	Node.js ≥ 20, any OS (Linux/macOS), ~512 MB RAM
iOS Agent	macOS, Xcode with iOS Simulator Runtime, Node.js ≥ 20
Android Agent	macOS, Android SDK (adb in $PATH or $ANDROID_HOME set), AVD with google_apis/arm64-v8a (android-34), Node.js ≥ 20
Browser (QA)	Any modern browser — Chrome, Firefox, Safari, Edge

Self-Hosting

Local (single Mac)

Relay and agent on the same machine — ideal for a single developer or small team.

tapflow start

Team (separate relay server)

Run the relay on a Linux server or dedicated Mac. Each Mac with simulators runs the agent.

Relay server:

# 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

Each Mac agent:

tapflow agent start --relay wss://your-relay-url

For nginx / Caddy reverse proxy setup and external access, see Self-Hosting the Relay.

CLI Reference

Command	Description
tapflow start	Start relay + agent together (local mode)
tapflow relay start	Start relay only
tapflow agent start --relay <url>	Start agent and connect to a relay
tapflow init	Create the first admin account
tapflow doctor	Diagnose environment (Node, Xcode, adb…)
tapflow devices	List available simulators and emulators
tapflow boot <name|udid>	Boot a simulator or emulator
tapflow status	Show connected agents, devices, active sessions
tapflow reset	Shut down all simulators and emulators
tapflow logs	Show recent relay log entries

Full reference → CLI docs

Documentation

jo-duchan.github.io/tapflow

• Introduction
• Quick Start
• Self-Hosting the Relay
• iOS Agent Setup
• Android Agent Setup
• Uploading Builds (CI/CD)
• CLI Reference
• Troubleshooting

Development

Requirements: Node.js ≥ 20, pnpm ≥ 9

git clone https://github.com/jo-duchan/tapflow.git
cd tapflow
pnpm install
pnpm dev

See CONTRIBUTING.md for branch strategy, commit conventions, and architecture overview.

License

MIT — Copyright © 2025-present tapflow contributors

tapflow bundles scrcpy-server (Apache-2.0) for Android screen streaming. See NOTICE for full attribution.