tapflow โ€” Quality for everyone.

A self-hosted Appetize / BrowserStack alternative for mobile QA teams

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

GitHub stars Docker pulls Latest release Last commit OpenSSF Best Practices GSF SCI self-certified (GSF-SCI-2026-00003)

๐Ÿ“– Docs  ยท  ๐Ÿš€ Quick Start  ยท  ๐ŸŽฅ Demo  ยท  ๐ŸŽฌ Setup

https://github.com/user-attachments/assets/dbba8bde-74b6-4fb9-bdb6-3919bc4295c4

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 ``` > A relay on a different machine accepts an agent only with an `agent`-scope token โ€” create one in **Settings โ†’ Tokens** (Admin only). Agents on the relay's own machine (`tapflow start`) need no token. See [Remote relay authentication](https://www.tapflow.dev/operate/agents#remote-relay-authentication). > > For nginx / Caddy reverse proxy setup and external access, see [External access](https://www.tapflow.dev/operate/external-access). ## CLI Reference | Command | Description | |---------|-------------| | `tapflow start` | Start relay + agent together (local mode) | | `tapflow relay start` | Start relay only | | `tapflow agent start --relay [--token ]` | Start agent and connect to a relay (remote relays need an `agent`-scope token) | | `tapflow init` | Configure this machine's tapflow (`~/.tapflow` by default) | | `tapflow admin init` | Create the first admin account (CLI fallback) | | `tapflow doctor [platform]` | Diagnose prerequisites (Node, iOS, Android) | | `tapflow setup [platform]` | Install & configure the local environment | | `tapflow devices` | List available simulators and emulators | | `tapflow boot ` | 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 (run on the relay host) | Full reference โ†’ [CLI docs](https://www.tapflow.dev/reference/cli) ## Documentation Full docs: **[www.tapflow.dev](https://www.tapflow.dev)** - **Guides** โ€” [Quick Start](https://www.tapflow.dev/get-started/quick-start) ยท [Environment Setup](https://www.tapflow.dev/operate/environment-setup) ยท [Self-Hosting](https://www.tapflow.dev/operate/deployment) ยท [Uploading Builds (CI/CD)](https://www.tapflow.dev/testing/app-center) ยท [Troubleshooting](https://www.tapflow.dev/troubleshooting) - **Reference** โ€” [CLI](https://www.tapflow.dev/reference/cli) ยท [Configuration](https://www.tapflow.dev/reference/configuration) ยท [REST API](https://www.tapflow.dev/reference/api) ยท [Security & Privacy](https://www.tapflow.dev/reference/security) - **AI Agent** โ€” [MCP Server](https://www.tapflow.dev/automation/mcp-server) ## Contributing tapflow is actively developed and PRs are welcome โ€” see [CONTRIBUTING.md](CONTRIBUTING.md) for branch strategy, commit conventions, and an architecture overview. For deep dives, the [contributor notes](CONTRIBUTING.md#technical-internals) cover the SimulatorKit reverse-engineering and the streaming render pipeline. Everyone taking part is expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md). **Requirements**: Node.js โ‰ฅ 22, pnpm โ‰ฅ 9 ```sh git clone https://github.com/jo-duchan/tapflow.git cd tapflow pnpm install pnpm dev ``` ## Recognition - Gold Prize (NIPA President's Award), Open Track โ€” [2026 Open Source Developer Contest (Korea)](https://osscontest.kr/notice/48) - Self-certified compliant with ISO/IEC 21031:2024 (SCI), verified by GSF โ€” [certificate GSF-SCI-2026-00003](https://badges.greensoftware.foundation/awards/sci/gsf-sci-2026-00003) ยท [disclosure](https://github.com/Green-Software-Foundation/certification/blob/main/submissions/gsf-sci-2026-00003/disclosure.md) ## License [MIT](LICENSE) โ€” Copyright ยฉ 2026-present tapflow contributors > tapflow bundles [scrcpy-server](https://github.com/Genymobile/scrcpy) (Apache-2.0) for Android screen streaming. See [NOTICE](NOTICE) for full attribution.