jo-duchan/tapflow

What it does

tapflow lets a mobile QA team open iOS Simulators and Android emulators in a normal browser instead of installing Xcode, Android Studio, or passing physical devices around. It splits the work into a self-hosted relay (Linux or macOS) that also serves the dashboard, a macOS agent that drives the simulators and connects outbound to the relay, and a browser dashboard for everyone else (architecture).

The stream uses H.264 and a two-tier decoder (WebCodecs on secure contexts, WASM/tinyh264 on plain HTTP) with JPEG fallback, so the media-element buffer is out of the decode path. The agent injects iOS touch directly without WebDriverAgent. Around the stream, the dashboard adds an App Center for .app.zip/.apk builds, session recordings kept about 72 hours, a screenshot REST endpoint, per-agent CPU/RAM monitoring, team roles, and Personal Access Tokens (features).

This is aimed at QA, product, and design teammates who need to check builds without owning a Mac toolchain. It is not a replacement for native development tools, not a device farm, and does not integrate external frameworks such as Appium or WebDriverAgent (scope). An experimental YAML flow runner and an MCP server for LLM agents are included.

Quick start

Prerequisites: Node.js 22 or newer. To run agents you need macOS 26 or 27 with Xcode 26 or 27 and an iOS Simulator runtime, or Java plus the Android SDK with an AVD (requirements).

1. Install the CLI: npm install -g tapflow.
2. On the Mac that will drive simulators, prepare the environment: tapflow setup. Skip this on a relay-only Linux host.
3. Start relay and agent together in local mode: tapflow start. It reports the relay on http://localhost:4000 and the connected agent with available simulators.
4. Open http://localhost:4000; tapflow redirects to /setup to create the admin account. On a headless server, run tapflow admin init instead.
5. Sign in at the dashboard. If prerequisites fail, tapflow doctor re-checks Node, iOS, and Android setup.

For a team, run tapflow relay start on a separate Linux host or Mac—PM2 or the tapflow/tapflow Docker image with a persistent volume are both documented—then point each Mac at it with tapflow agent start --relay wss://your-relay-url --token <agent-token> (self-hosting).

Constraints and operations

Agents must run on macOS because they drive the Simulator and emulator; only the relay is portable. The relay handles accounts, builds, and live device control, so it is the trust boundary: off-host connections require sign-in, and remote agents need an agent-scope token. Traffic through a tunnel counts as off-host even when the tunnel client runs on the relay host (security).

The Docker image is relay-only and needs a volume for the sign-in secret; invite links also require TAPFLOW_RELAY_URL. Device-to-dashboard clipboard copy needs HTTPS or localhost. Session recordings purge automatically after roughly 72 hours. The flow runner and MCP server are labeled experimental. The project is MIT-licensed and bundles scrcpy-server for Android streaming.

HotRepo's take

On the 2026-11-04 TypeScript daily list, tapflow gained 26 stars and reached 10th place for that day, with 1,585 stars and 169 forks overall. A Show HN post from 2026-06-10 drew only 4 points and no comments; the more active discussion was a 2026-06-22 write-up on a 0.5s periodic hitch traced to macOS AWDL, where a commenter noted similar warnings from cloud game streaming on Macs. The README's own latency note claims p50 decode-to-present of about 11–17 ms on a LAN with the WASM decoder, so the AWDL experience is a useful reminder that end-to-end smoothness depends on host-level networking, not just the streaming path.