Demo

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: [email protected]
# ? 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.