https://github.com/user-attachments/assets/dbba8bde-74b6-4fb9-bdb6-3919bc4295c4
v0.x, actively developed — backward-compatible by default; breaking changes are rare and always noted in the changelog. Roadmap →
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.
How it works
tapflow connects three parts:
- A self-hosted relay (Linux or Mac) — also serves the dashboard on the same port, so there's no separate web server.
- 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.
- 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.
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: three ways to use one shared layer, and work that moves from something done once to something every build runs.
Quick Start
1. Install
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:
tapflow setup
Skip this on a relay-only server (Linux). See Environment Setup for details.
3. 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).
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 initto 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 doctorto re-check prerequisites at any time.
Requirements
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
- 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/.apkand 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/screenshotfor 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 runreplays a YAML flow with condition-based waits and a JUnit report, and calls no LLM at replay time. Experimental. - MCP Server —
@tapflowio/mcp-serverlets 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 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.
- 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 anagent-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:writefor CI uploads,agentfor remote agents), and team roles (Admin / Developer / QA / Viewer) govern dashboard access.
Found a vulnerability? See SECURITY.md. For the full model, read Security & Privacy.
Self-Hosting
A single Mac needs nothing beyond tapflow start (see 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:
# 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:
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 for the full setup.
Each Mac agent:
tapflow agent start --relay wss://your-relay-url --token <agent-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.For nginx / Caddy reverse proxy setup and external access, see External access.
CLI Reference
Full reference → CLI docs
Documentation
Full docs: www.tapflow.dev
- Guides — Quick Start · Environment Setup · Self-Hosting · Uploading Builds (CI/CD) · Troubleshooting
- Reference — CLI · Configuration · REST API · Security & Privacy
- AI Agent — MCP Server
Contributing
tapflow is actively developed and PRs are welcome — see CONTRIBUTING.md for branch strategy, commit conventions, and an architecture overview. For deep dives, the contributor notes cover the SimulatorKit reverse-engineering and the streaming render pipeline. Everyone taking part is expected to follow the Code of Conduct.
Requirements: Node.js ≥ 22, pnpm ≥ 9
git clone https://github.com/jo-duchan/tapflow.git
cd tapflow
pnpm install
pnpm dev
License
MIT — Copyright © 2026-present tapflow contributors
tapflow bundles scrcpy-server (Apache-2.0) for Android screen streaming. See NOTICE for full attribution.
