convez.ai
MCP ServerDevOps & InfraestruturaAvançado
jo-duchan

Tapflow

jo-duchan/tapflow

Simuladores iOS e Android self-hosted para QA mobile em browser

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que funciona como alternativa self-hosted ao Appetize/BrowserStack para testes de QA mobile. Permite executar simuladores iOS e emuladores Android em navegadores sem setup de toolchain, mantendo builds, streams e gravações em infraestrutura própria da equipe.

Instalação

$npx convez-ai jo-duchan/tapflow

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2,3 mil
Forks
220
Acompanhando
11
Saúde
85%
Último commit
há 6 horas
Versão
v0.33.0
Issues abertas
65
Contribuidores
3

Casos de uso

  • Testes de aplicativos móveis sem acesso local a Xcode ou Android Studio
  • Compartilhamento remoto de simuladores entre desenvolvedores, PMs e designers
  • Testes de compatibilidade cross-device sem adquirir múltiplos dispositivos físicos

Veredito

Solução robusta para equipes de QA mobile que dispõem de infraestrutura própria (Macs) e buscam reduzir custos de serviços cloud. Exige setup técnico considerável (relay server, agente macOS) mas elimina dependências de terceiros e mantém segurança dos builds internos.

README

A tradução para o português deste README ainda está na fila.

v0.x: tapflow is under active development. Breaking changes may appear in minor versions until v1.0.0. See ROADMAP for the full plan.


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.

SolutionThe catch
Appetize / BrowserStackRecurring cost — and app builds are uploaded to a third-party cloud
Physical devicesCost, availability, OS coverage, management overhead
Xcode / Android StudioEach teammate needs a Mac and a full mobile toolchain
tapflowReuse your own Macs — data stays on infrastructure you control, and the whole team does QA from a browser

What tapflow does

tapflow connects three parts:

  1. A self-hosted relay server (Linux or Mac)
  2. A macOS agent that drives iOS simulators and Android emulators
  3. A browser dashboard for the rest of the team

The agent connects outbound to the relay. Teammates open the dashboard, pick an available device, and interact with it remotely — while the simulators and emulators keep running on your own Macs.

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 — it isn't an automation framework or a device farm.

How it works

Browser (your 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. Anyone on the team 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

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.

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, the iOS toolchain, adb, and other prerequisites.

Requirements

ComponentRequirements
Relay serverNode.js ≥ 20, any OS (Linux/macOS), ~512 MB RAM
iOS AgentmacOS, Xcode with the iOS Simulator runtime, Node.js ≥ 20
Android AgentmacOS, Android SDK (adb in $PATH or $ANDROID_HOME set), an AVD with google_apis/arm64-v8a (android-34), Node.js ≥ 20
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 — app builds, device streams, recordings, and account data stay on infrastructure you control.
  • 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.
  • 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.
  • MCP Server (experimental) — @tapflowio/mcp-server lets Claude Code and other LLM agents control simulators as native tools.

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 performance & latency reference 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.

DataWhere it stays
App binaries (.app.zip / .apk)Relay storage
Device streams (video · touch)The relay ↔ browser path you host
Session recordingsRelay storage; expire after 72h, then purged
Account & team dataThe relay's SQLite DB
Third-party simulator cloudNot required
  • LAN-first — the agent ↔ relay leg is internal traffic; the device stream never transits a third party.
  • PAT + roles — Personal Access Tokens carry scopes (e.g. builds:write for CI uploads), 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

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

CommandDescription
tapflow startStart relay + agent together (local mode)
tapflow relay startStart relay only
tapflow agent start --relay <url>Start agent and connect to a relay
tapflow initScaffold tapflow.config.json
tapflow admin initCreate the first admin account (CLI fallback)
tapflow doctorDiagnose environment (Node, iOS toolchain, adb…)
tapflow devicesList available simulators and emulators
tapflow boot <name|udid>Boot a simulator or emulator
tapflow statusShow connected agents, devices, active sessions
tapflow resetShut down all simulators and emulators
tapflow logsShow recent relay log entries

Full reference → CLI docs

Documentation

www.tapflow.dev

Getting Started

Setup

Dashboard

AI Agent

Reference

Troubleshooting

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.

Requirements: Node.js ≥ 20, 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.

Ver o original no GitHub

Bom para

Relacionados