Deployment options
The relay is a lightweight Node.js server. It routes WebSocket traffic and serves the dashboard, so it needs little CPU or memory. The agent is what drives simulators and emulators, and it runs on a Mac. Most teams start with one Mac running both.
Choose a setup
| Setup | Fits when | Start with |
|---|---|---|
| Single Mac | One Mac runs the simulators, and teammates are on the same network | tapflow start |
| Separate relay | Several Macs run simulators, and one always-on Mac serves the dashboard | tapflow relay start, then tapflow agent start on each Mac |
| Relay in Docker | The relay lives on a Linux server or NAS, and agents stay on Macs | docker compose up -d |
Two things are added on top of any of them: External access for teammates outside the office network, and HTTPS for a smoother stream.
Keep agents and the relay on the same wired LAN
The agent streams video frames to the relay continuously, so the two must share a LAN. Different floors or VLANs in one building are fine, because internal routing keeps latency low. Placing an agent across the internet raises RTT and drops frames. Wired Ethernet is recommended; Wi-Fi works but can stutter on a Mac (AWDL), so see Stream lag or stuttering if playback hitches.
Single Mac
The relay and the agent run on the same Mac, started by one command:
tapflow startThe banner prints the address teammates open, http://<this Mac's LAN IP>:4000. The relay generates its own JWT_SECRET, so there is nothing else to set. Quick Start walks through this setup from install to the first tap.
Separate relay
The relay runs on one always-on Mac, and an agent runs on each Mac with simulators or emulators.
On the relay Mac:
tapflow relay startOn each agent Mac:
tapflow agent start --relay ws://192.168.x.x:4000 --token tflw_pat_xxxxxxxxAn agent on a different machine than the relay needs an agent-scope token. Remote relay authentication shows how to create one. The scheme is ws://, or wss:// when the relay serves HTTPS; the relay prints the exact command when it starts.
Relay in Docker
The official image runs the relay only. Agents still run on Macs on your LAN and connect to the Docker host with an agent-scope token, the same way as with a separate relay. The Compose file, the required data volume and the first account are in Deploy with Docker.
Teammates on the same network
Teammates open http://<relay LAN IP>:4000 in a browser. The port is local.port in tapflow.config.json (default 4000). Nothing needs to be installed on their side. To pin a fixed signing key instead of the generated one, see JWT_SECRET.
Moved sections
Sections that used to be on this page now live on these pages.