# tapflow > tapflow is an open-source, self-hosted tool that lets your entire team — PO, PM, designers, backend engineers, and QA — run iOS simulators and Android emulators directly in the browser. No IDE, no device setup, no data leaving your network. > > It is a self-hosted, open-source alternative to cloud testing services like Appetize and BrowserStack App Live. Unlike those services, tapflow runs on Macs your team already owns, so your app binaries and test data never leave your network. > > Architecture: a Mac Agent connects outbound to a Relay server; team members open the dashboard in any browser and interact with the simulator in real time. The Relay also exposes a REST API and an MCP server for LLM-based automation. > > Two testing paths: > - Manual review (primary): CI uploads a build → team tests in the browser > - AI Agent via MCP (experimental): an LLM agent controls the simulator using @tapflowio/mcp-server > > Every page below is also served as its source markdown at the same URL with a `.md` suffix, and all of them concatenated are at https://www.tapflow.dev/llms-full.txt. Korean translations of every page live under `/ko/` with the same paths and the same content. > > Read the page you need rather than the concatenation. A tool that truncates or summarises a large fetch loses the end of `llms-full.txt`, which is where the reference pages are — the CLI, the REST API and every configuration key. ## Get started - [Introduction](https://www.tapflow.dev/get-started/introduction): Architecture overview, key concepts (Relay, Agent, Dashboard, MCP Server), and streaming format by platform. - [Quick Start](https://www.tapflow.dev/get-started/quick-start): Install tapflow, start the relay and agent, create the admin account, and open the dashboard — under 5 minutes. - [First-time Setup](https://www.tapflow.dev/dashboard/setup): Create the admin account, sign in, invite teammates with roles (Admin / Developer / QA / Viewer), add the first app, and start a session. ## Test apps - [Test apps](https://www.tapflow.dev/testing): Where teammates test builds in the dashboard: App Center lists the uploaded builds, and a QA Session streams a device to your browser. - [Uploading Builds](https://www.tapflow.dev/testing/app-center): Upload iOS (.app.zip) or Android (.apk) builds from the dashboard. Builds are linked to apps by bundle ID automatically. ### QA Session - [QA Session](https://www.tapflow.dev/testing/qa-session): The full-screen device view: pick a Mac and a device to start a session, then touch, swipe, open deep links, record, and comment on the build. - [Network Control](https://www.tapflow.dev/testing/network-control): Take a simulator or emulator offline from the toolbar and bring it back. Exactly which connections are cut and which are not, why localhost is exempt, and why iOS needs the bundled network extension. - [Audio](https://www.tapflow.dev/testing/audio): Device audio in the browser — on by default on both platforms, the one-time permission, per-agent opt-out with TAPFLOW_AUDIO=off, volume, and why the agent Mac itself stays silent. ## Operate ### Set up a Mac - [Requirements](https://www.tapflow.dev/operate/requirements): Node.js ≥ 22 for relay and agent; Xcode for iOS; Android SDK + AVD for Android; any modern browser for the dashboard. Names the verified macOS and Xcode versions. - [Environment Setup](https://www.tapflow.dev/operate/environment-setup): `tapflow doctor` to diagnose what a Mac is missing, and `tapflow setup` to install and configure it — per platform, including the Xcode license and first-launch steps that need sudo. - [Configuring tapflow](https://www.tapflow.dev/operate/configure): `tapflow init` and the `tapflow.config.json` it writes — tunnel choice, streaming profile on a LAN, certificate method, and the `.env` that holds secrets. Skippable if port 4000 over HTTP with no tunnel is fine. - [Agent Setup](https://www.tapflow.dev/operate/agents): Start the Mac agent and connect it to the relay. iOS prerequisites (Xcode, Simulator Runtime), Android prerequisites (AVD with google_apis/arm64-v8a image), and authenticating a remote agent with a PAT. - [iOS Network Extension](https://www.tapflow.dev/operate/network-extension): Install and approve the network extension that iOS network control needs on the agent Mac, and recover when replacing it cuts the Mac off or a device comes back online by itself. ### Deploy the relay - [Deployment Options](https://www.tapflow.dev/operate/deployment): Choose where the relay runs — on the same Mac as the agent, or on a separate relay server — and how teammates on the same network reach it. - [Deploy with Docker](https://www.tapflow.dev/operate/docker): Run the relay from the official Docker image on an always-on LAN box: the Compose file, the required volume, the relay URL for invite links, and creating the first account. - [External Access](https://www.tapflow.dev/operate/external-access): Reach the relay from outside the office through an outbound tunnel — Tailscale for tailnet members, or rathole through a VPS you own for a public URL — with optional HTTPS for the Smooth profile. - [Streaming Quality](https://www.tapflow.dev/operate/streaming-quality): The three streaming profiles (Standard / Smooth / Remote), which one a viewer gets from how it connects, the decoder and resolution behind each, and how to tune the resolution. - [Backups & Uptime](https://www.tapflow.dev/operate/relay-operations): Back up the relay's data directory (Litestream for SQLite), and keep the relay running with PM2 on a Mac or systemd on Linux. ### Run the team - [Team, Roles & Tokens](https://www.tapflow.dev/operate/team-and-roles): The dashboard's Settings pages: your profile, the member list with roles and invitations (Admin only), and personal access tokens (PATs) for CI and remote agents. - [Scaling Mac Resources](https://www.tapflow.dev/operate/scaling): Add more Mac hosts to the same relay for a larger device pool. Agent naming, per-Mac device limits, and monitoring via Mac Resources tab. ### Deliver builds - [Build Distribution](https://www.tapflow.dev/operate/ci-distribution): Connect your CI pipeline to upload builds automatically. Includes Personal Access Token setup, curl examples, GitHub Actions full example with branch/commit metadata, and build status reference. - [Webhooks](https://www.tapflow.dev/operate/webhooks): Register a URL that tapflow POSTs to when someone moves a build to Done or Rejected — the review verdict, not a build completion. Payload shape, signature verification, and when it fires. ### AI automation (MCP and flows — experimental) - [MCP Server](https://www.tapflow.dev/automation/mcp-server): Install and configure @tapflowio/mcp-server. Supports Claude Code, Codex, Cursor, and any MCP-compatible client. Available tools: list_builds, list_devices, connect_device, disconnect_device, boot_device, shutdown_device, screenshot, query_ui_tree, tap, swipe, type_text, press_key, press_button, install_app, launch_app, run_flow. - [Flow Reference](https://www.tapflow.dev/automation/flows): The YAML flow format replayed deterministically by `tapflow flow run` with no LLM calls — file structure, every step type, selectors, running in CI, and how it relates to the `run_flow` MCP tool. - [MCP in CI/CD](https://www.tapflow.dev/automation/mcp-ci): Run automated smoke tests on every build using claude CLI + MCP. Includes GitHub Actions example, multi-device matrix, example test prompts, and tips for reliable agentic test scripts. ## Reference - [CLI Reference](https://www.tapflow.dev/reference/cli): Every command with a section on that page — doctor, setup, init, admin init, start, relay start, agent start, devices, boot, reset, status, logs, migrate, migrate data-dir, migrate net-filter. `tapflow flow run` is documented under Flow Reference instead. - [Configuration](https://www.tapflow.dev/reference/configuration): tapflow.config.json schema and environment variable overrides (JWT_SECRET, TAPFLOW_PORT, TAPFLOW_DATA_DIR, SMTP_*, etc.). - [REST API](https://www.tapflow.dev/reference/api): Full REST API reference — Auth, Invitations, Password reset, Apps, Builds, Comments, Team, Tokens, Profile, Settings, Recordings, Agents, Logs. Base path: /api/v1/. - [Security & Privacy](https://www.tapflow.dev/reference/security): How tapflow keeps data on-prem — build files, device streams, and session recordings never leave your network. LAN-first architecture, PAT-based authentication with scopes, and TLS via reverse proxy. - [Performance & Latency](https://www.tapflow.dev/reference/performance): What tapflow streaming actually measures — bandwidth, decode latency on the WASM (tinyh264) path over a real LAN, the glass-to-glass estimate against the ~100 ms direct-manipulation budget, known limitations, and how to reproduce the numbers. - [Sustainability](https://www.tapflow.dev/reference/sustainability): Why reusing Macs a team already owns lowers the hardware footprint of mobile QA — embodied carbon, the SCI standard, what we measured, and the limits of the claim. ## Troubleshooting - [Troubleshooting](https://www.tapflow.dev/troubleshooting): Fixes for tapflow problems, grouped by area — install and agents, iOS simulator, Android emulator, builds, streaming, and sign-in — and how to read the relay's logs. - [Install & Agents](https://www.tapflow.dev/troubleshooting/install-and-agents): An agent that will not start or connect, `tapflow doctor` failures, and a relay that uses a configuration you did not expect. - [iOS Simulator](https://www.tapflow.dev/troubleshooting/ios-simulator): `spawn unknown error`, the CoreSimulator service version mismatch, a simulator that cannot be located on disk, and Korean input on iOS 17 and earlier. - [Android Emulator](https://www.tapflow.dev/troubleshooting/android-emulator): An emulator stream that does not start, colors that look less saturated than the emulator window, and an emulator that slows down when the Mac is unattended. - [Builds & Uploads](https://www.tapflow.dev/troubleshooting/builds): iOS upload errors (.ipa vs .app.zip), INSTALL_FAILED_NO_MATCHING_ABIS on Apple Silicon, and an APK that shows as Unversioned or merges into the wrong app. - [Stream & Sessions](https://www.tapflow.dev/troubleshooting/streaming): A stream that lags or stutters — Wi-Fi (AWDL), host load, display sleep, low resolution on a LAN — and a session that ends by itself. - [Sign-in & Accounts](https://www.tapflow.dev/troubleshooting/accounts): `tapflow admin init` reporting Already initialized, and an invitation or password reset link that has expired. ## Contributing - [Contributing Guide](https://www.tapflow.dev/contributing): The monorepo's package layout, where each platform's agent lives, and how to report a bug. The full contributing guide is CONTRIBUTING.md in the repository.