SkillAgentSearch skills...

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/RoamRun

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

78/100

Supported Platforms

Claude Code
Claude Desktop

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.

Substance
21/30
Structure
20/20
Description
15/15
Adoption
7/20
Freshness
15/15

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 found

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.

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.

SkillScoreStarsUpdatedFormat
RoamRun (this skill)by mh-mobile784810d agoMCP Server
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.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.
<p align="center"> <img src="docs/images/icon.png" width="128" height="128" alt="RoamRun icon"> </p> <h1 align="center">RoamRun</h1> <p align="center"><strong>Run your iOS apps wherever your device is.</strong></p> <p align="center"> <a href="https://github.com/mh-mobile/RoamRun/actions/workflows/ci.yml"><img src="https://github.com/mh-mobile/RoamRun/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="LICENSE"><img src="https://img.shields.io/github/license/mh-mobile/RoamRun" alt="License: MIT"></a> <img src="https://img.shields.io/badge/macOS-13%2B%20Apple%20Silicon-blue" alt="macOS 13+ on Apple Silicon"> </p> <p align="center"><a href="https://mh-mobile.github.io/RoamRun/">Website</a> · English | <a href="README.ja.md">日本語</a></p> <p align="center"><img src="docs/images/main.png" width="800" alt="RoamRun main window: iPadPro ready for Xcode over Tailscale"></p>

RoamRun 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:

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 with log 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 logs and roamrun run --logs use devicectl'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

  1. With the device on USB or on the Mac's Wi-Fi: menu bar icon › Open RoamRun › Add Device.
  2. 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.
  3. Press Start Bridge, and wait for "Ready for Xcode" (or "On this Wi‑Fi").
  4. 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 -d waits up to 60 seconds for Ready (or On this Wi‑Fi) and exits

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars48
CategoryDevelopment
Updated10d ago
Forks6

Languages

Swift

Trust signals

97/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 info