The Problem
Mobile QA teams need to run simulators or emulators on any machine, but the usual approaches force each teammate to keep a Mac or an Android Studio installation. Uploading internal builds to a third‑party service adds cost and security risk. The result is a fragmented workflow where backend developers, product managers, and designers cannot inspect a build without a developer’s machine.
What This Does
tapflow is a self‑hosted relay that runs on Linux or macOS and serves a browser‑based dashboard. It connects to a macOS agent that launches Xcode simulators or Android emulators, streams the video over H.264, and records interactions for playback. Key files:
packages/agent-core/src/index.ts– bootstraps the relay and HTTP server.packages/android-agent/src/index.ts– starts the Android emulator and forwards input.packages/audiotap-helper/src/index.ts– injects audio streams into the relay.
The dashboard lives in packages/dashboard and is bundled with the relay, so a single binary exposes all UI and API endpoints.
How It Is Wired
INTERNAL CALL GRAPH
packages/agent-core/src/index.tsstarts the Express server (packages/agent-core/src/server.ts).- Requests hit
/api/v1/agents→packages/agent-core/src/handlers/agent.ts. - The handler spawns a child process:
packages/android-agent/src/index.ts(for Android) orpackages/ios-agent/src/index.ts(for iOS). - The agent launches the simulator/emulator, opens a WebSocket to the relay, and streams video via H.264.
packages/agent-core/src/utils/index.tscontains shared utilities (e.g.,createSocket,recordFrame) that all agents use.
WHAT THIS CODE TOUCHES OUTSIDE ITSELF
- Filesystem: reads build artifacts from
./buildsand writes recordings to./recordings. - Network: listens on
process.env.PORT(default 3000) and serves WebSocket connections at/ws. - Database: no persistent DB; session data lives in memory or in the
./statedirectory.
WHAT EACH FILE IS RESPONSIBLE FOR
packages/agent-core/src/index.ts– entry point, process lifecycle.packages/agent-core/src/server.ts– router, middleware.packages/agent-core/src/handlers/agent.ts– agent lifecycle, WebSocket orchestration.packages/android-agent/src/index.ts– Android emulator launch, frame capture.packages/audiotap-helper/src/index.ts– audio capture and injection.
The relay is the hub; changing its port or TLS settings only requires editing packages/agent-core/src/config.ts.
How To Use It
Setup
# Clone the repo
git clone https://github.com/moses-y/tapflow
cd tapflow
# Install dependencies (pnpm is used)
pnpm install
# Build the docker image (optional)
docker build -t tapflow/tapflow .
Configuration
packages/dashboard/.env.developmentholds local secrets; copy.env.exampleif present.- Set
RELAY_PORTandAGENT_HOSTin the environment or inpackages/agent-core/src/config.ts. - Place build artifacts in
./builds/<platform>/<build-id>.zip.
Running it
# Start the relay with the dashboard
pnpm run start:relay
# Or use Docker
docker run -p 3000:3000 tapflow/tapflow
The web UI is available at http://localhost:3000. From there, click “Start Agent” to launch a simulator on the host.
Real‑World Use
A CI pipeline in docs/automation/mcp-ci.md shows how to trigger a tapflow run from GitHub Actions. A script in .github/workflows/docker-publish.yml builds the image, tags it, and pushes to Docker Hub. During a release, the team spins up the relay, runs tests against the hosted simulators, and uploads the recordings to a shared artifact bucket for later review.
Code Health & Issues
- Low/Secret –
packages/dashboard/.env.developmentcontains test secrets; the audit flagged this but the repo includes a clear.env.example. - Low – TLS test certificates in
packages/relay/src/__tests__/fixturesare benign. - No critical security findings – the static analysis did not flag any hard‑coded credentials or insecure defaults.
- Test coverage – 540 test files cover most core modules; CI (
.github/workflows/ci.yml) runs the full test suite.
The Bottom Line
tapflow delivers a straightforward, zero‑buffer streaming solution that keeps builds and recordings on your own infrastructure. Its monorepo structure is clear, with a single entry point (packages/agent-core/src/index.ts) and well‑defined agent subsystems. The Docker support and extensive CI configuration make it easy to integrate into existing pipelines. For teams that need shared simulator access without cloud costs, tapflow is a practical, well‑maintained choice.