RoamRun
Run and debug your iPhone from Xcode wherever it is — keeps wireless debugging working over Tailscale when the iPhone is on another network.
Install / Use
claude mcp add mh-mobile -- npx -y github:mh-mobile/RoamRunIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of RoamRun
RoamRun scores 78/100 on our quality scale, 3705th of 4,698 Development & Engineering skills we index.
Its MCP Server is 49 KB long, well organised into 47 sections with 16 code examples: long enough that it reads more like full documentation than a focused instruction file, which agents can find harder to follow.
It has 48 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 10 days ago, so RoamRun is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-11-15. Automated pattern scan on 2026-11-15. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
RoamRun compared with similar skills
All 4 of these similar skills score higher than RoamRun; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| RoamRun (this skill)by mh-mobile | 78 | 48 | 10d ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
Frequently asked questions
- How do I install RoamRun?
- Run
claude mcp add mh-mobile -- npx -y github:mh-mobile/RoamRun. The install tabs above show the steps for each supported agent. - Which AI agents does RoamRun work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is RoamRun safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is RoamRun still maintained?
- The repository was last updated 10 days ago, so RoamRun is actively maintained.
Skill content
View source on GitHubRoamRun is a macOS menu bar app, with a roamrun command, that makes Xcode's wireless debugging
work over Tailscale or another mesh VPN. An iPhone, iPad, Apple Vision Pro or Apple TV on a different
network from the Mac stays visible to Xcode and devicectl as a local device: you can build,
install, launch and debug as usual. RoamRun calls that connection a bridge.
It also does three related things:
- Shows and operates the device's screen from the command line or from an AI agent (Seeing and operating the device).
- Pairs a Mac that was never near the device — a cloud Mac, for example (A Mac the device was never near).
- Lets a device install a build by itself, with no bridge and no pairing (Installing without the bridge).
For a machine without RoamRun — Linux, Windows, or another Mac — there is a separate command,
roamrunctl. With it, a CI job can install and launch your app on your
device (Installing and launching from CI).
Why it is needed
Since iOS 17, wireless debugging finds devices with Bonjour (_remotepairing._tcp). Bonjour
stays on the local network, so it does not cross a VPN such as Tailscale. The Mac's
remotepairingd also ties its connection to the network interface where it found the device (as
seen), so advertising the device's VPN address is not enough either.
RoamRun tells Xcode that the device is on the same Wi-Fi, and carries the traffic over the VPN:
flowchart LR
subgraph mac["Mac at home"]
xcode["Xcode / devicectl"] --> rpd["remotepairingd<br/>(Apple)"]
fake["Stand-in Bonjour record<br/>(pointing at this Mac)"]
relay["RoamRun relay<br/>(on the Mac's LAN interface)"]
end
subgraph away["Away"]
iphone["iPhone<br/>(on some Wi-Fi)"]
end
rpd -. "① looks for the iPhone" .-> fake
rpd -- "② connects to this Mac" --> relay
relay == "③ over Tailscale" ==> iphone
Pairing verification and encryption stay end to end between the Mac and the device, as Apple implements them. RoamRun relays bytes; it does not read or change them. The details are in docs/how-it-works.md.
Requirements
- A Mac with Apple silicon on macOS 13 or later, and an administrator account. RoamRun reads
remotepairingd's log withlog stream, and stops with a message when macOS answers that an administrator is required. - A device on iOS 17.4 or later. RoamRun relays TCP only; it has no support for the QUIC tunnel of iOS 17.0–17.3. iPad, Apple Vision Pro and Apple TV were also used; "device" below means any of the four. Apple Watch has not been tried, as there was none at hand. Tailscale has no app for watchOS, so a watch can't be bridged on its own; whether one is reached through its iPhone's bridge is not known.
- Xcode with
devicectl(Xcode 15 or later) that supports the device's iOS version; see Apple's table.roamrun logsandroamrun run --logsusedevicectl's--console, which came with Xcode 16. - Tailscale, or another mesh VPN where you enter the device's address by hand, connected on both the Mac and the device.
- The device paired with this Mac once, with Developer Mode on: over USB, or with Xcode 27 and iOS 27 on the same Wi-Fi (Device Hub › + › Pair Nearby Device).
- The device on a Wi-Fi network when the bridge starts. On cellular alone the device did not answer when tried. Once the bridge is Ready the device can move to cellular and keep its session, if Keep debugging on cellular is on (it is off by default); see Working away from the Mac.
Seeing and operating the device needs iOS 27 or later. Pairing a far Mac for Xcode needs iOS 27 and Xcode 27.
Install
With Homebrew:
brew install --cask mh-mobile/tap/roamrun
This installs RoamRun.app in /Applications and links the roamrun command. To update:
brew upgrade --cask roamrun.
Without Homebrew, download the dmg from
Releases, drag RoamRun to Applications and open
it. The first screen offers to install the roamrun command; later it is under Open RoamRun ›
Settings › Command line tool › Install…. To update, quit RoamRun and replace the app. There is no
automatic update. Saved devices stay, and bridges that were running start again.
The app is signed with a Developer ID and notarized by Apple.
To build from source you need Xcode 26 or later and Rust from rustup (make
builds device control's library with the Rust version the repository names):
git clone https://github.com/mh-mobile/RoamRun && cd RoamRun
make run # builds RoamRun.app here and opens it; quit an installed RoamRun first
make install-cli # links /usr/local/bin/roamrun to this build (BINDIR=$HOME/bin for another place)
A build without a signing certificate is signed ad hoc, and macOS treats each rebuild as another
app. If you set up device control (seeing and operating the device) with such a build, the
Keychain asks about RoamRun's key after every rebuild: answer "Always Allow". On a Mac reached
over SSH only there is no screen to answer on, and the new build cannot read the saved pairings:
delete the two Keychain items (see
What it creates on your Mac) and set up or import
the pairing again. make app signs with an Apple Development certificate when the keychain holds
one.
Usage
- With the device on USB or on the Mac's Wi-Fi: menu bar icon › Open RoamRun › Add Device.
- Pick the device from the list, match it to the same device on Tailscale (or enter an address), and give it a name. The commands below take that name.
- Press Start Bridge, and wait for "Ready for Xcode" (or "On this Wi‑Fi").
- The device stays in Xcode's Devices window. Build, install and debug as usual.
While the device is on the Mac's own Wi-Fi the bridge stands aside and shows "On this Wi‑Fi": Xcode reaches the device directly. When the device moves to another network, the bridge takes over by itself. When the Mac's address changes, the bridge restarts.
<p align="center"> <img src="docs/images/add-device.png" width="520" alt="Add Device sheet"> <img src="docs/images/menu.png" width="260" alt="Menu bar menu"> </p>Working away from the Mac
You can leave the Mac at home and run the whole build-and-try loop from the device in your hand.
To start a bridge, the device has to be on a Wi-Fi with internet access. A café's or hotel's Wi-Fi, a pocket router, or another phone's hotspot all serve. Cellular alone does not, and neither does the device's own hotspot, since the device is then not on a Wi-Fi itself.
To keep a session on cellular, turn on Settings › Network › Keep debugging on cellular. It is off by default, because with it on every Run uses the device's mobile data. It applies only from Ready for Xcode, the bridged state. When the device shows "On this Wi‑Fi", Xcode reaches it over the local network, so leaving home straight onto cellular ends the session. To avoid that, keep the device on a Wi-Fi that another device makes even at home — a travel router, or a spare phone sharing its connection — so that RoamRun bridges it from the start.
A new session needs Wi-Fi again, for example after the device restarts. With the setting off, RoamRun closes the session when the device leaves Wi-Fi and reconnects when it is back.
On a Wi-Fi with a sign-in page, sign in first. Joining a Wi-Fi marked "No Internet Connection" and
sending traffic over cellular did not work when tried. Where a network blocks UDP, Tailscale goes
through its relay servers: that works, more slowly, and roamrun doctor shows the path.
Three ways to drive the Mac from the device:
| Method | On the device | Good for |
|---|---|---|
| An AI agent | A feature for driving an agent on your Mac from your phone, such as Claude Code's Remote Control or Codex in the ChatGPT app | Asking "build it and run it on my iPhone", looking at the result, and repeating |
| A terminal over SSH | An SSH client and Tailscale | Using roamrun, xcodebuild, devicectl and lldb directly |
| The Mac's screen | Screen Sharing or a VNC client, and Tailscale | Xcode's Run and breakpoints in its window |
Away from home, running with the debugger takes longer than at home: attaching lldb takes hundreds of round trips. With a 600 KB app over tethering it took about a minute with the debugger and about 4 seconds without. When you don't need breakpoints, turn off "Debug executable" under Edit Scheme › Run › Info. When you do, turning off "Queue Debugging" (Options) and "Main Thread Checker" (Diagnostics) there made it faster.
The agent features in the table send your conversation through each service's servers. Check your company's policy before using them on a work Mac.
CLI
The app's binary is also the roamrun command, for use over SSH or in scripts.
roamrun devices # saved devices (name, UDID, id) and their status
roamrun up <name> # start a bridge and show its progress; it runs until Ctrl-C
roamrun up <name> -d # start it in the background; it survives closing the terminal
roamrun status <name> # exits 0 when Xcode can use the device
roamrun down <name> # stop a bridge, whether the app or another terminal started it
roamrun doctor # check Mac → Tailscale → device step by step, and say how to fix
roamrun run <name> [--scheme S] [--logs] # in a project folder: build, install, launch
roamrun install <name> <App.ipa|App.app> # install a build signed for the device
roamrun logs <name> <bundle-id> # relaunch the app and stream its print / os_log output
roamrun screenshot <name> [file.png] # save the device's screen as PNG and print the path
roamrun ota [<name>] <App.ipa> [--replace] # publish a build for a device to install by itself
<name> is the name you gave the device in RoamRun. It is
case-insensitive and unique; roamrun devices lists the names, and the pencil on the device's page
renames it. The name in the device's Settings app is a separate one. When no saved device has that name, the device's Tailscale name (iphone-15-pro, as roamrunctl takes it, not the whole iphone-15-pro.tail1234.ts.net) works too, and so does its id or its first eight or more characters. A device is added in the app, or from the command line with
roamrun devices add <line> (a line that another Mac made), roamrun key import <file>,
roamrun pair xcode --with <Tailscale name> or roamrun pair control --with <Tailscale name>. All four are described
below.
What each command does, more exactly:
up -dwaits up to 60 seconds for Ready (or On this Wi‑Fi) and exits
Truncated for display — read the full file on GitHub.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
