Run your app and tests

From your repository or folder to the app running on the phone, built with Xcode 27.1. Your agent gets the app's first screen and the test results, and the next build is incremental.

1. Put the project on the phone

The project goes into the account's workspace, shared only by phones with the same label. Only what changed is written.

From git phone_app_run with git, an https link. path is the project's folder in it, ref a branch, tag or commit.

From your folder, over NoMac's CLI MCP local_path sends the folder in the same call, only the files the phone lacks.

From your folder, anywhere else phone_upload_link answers one shell command that packs the folder and sends it. Then pass the upload it answered.

From a terminal After simulator-use cloud start, simulator-use run sends and runs the project in the current folder.

A private repository on github.com, gitlab.com or bitbucket.org needs a token: secret names one of the account's secrets that holds it, or token sends it with the call, used for that fetch and kept nowhere. Never paste a token into a chat: request_secret gives the person a link to enter it.

2. Build and launch

MCP call

phone_app_run  { "git": "https://github.com/acme/app", "path": "ios", "scheme": "App" }

It builds the project for the Simulator, installs it, launches it and answers with its first screen as text. Build errors come back as file:line. A build past 40 seconds answers with a job that phone_job_status waits for. Later runs reuse the project, so a one-line change rebuilds and runs in about 7 seconds.

• scheme The only scheme, or the one named like the project, by default.

• configuration Debug by default.

• env The app's launch variables, as "API_URL=https://staging.example MODE=test", read from ProcessInfo. Kept for relaunches until the phone stops; "" clears them.

• permissions iOS's permission prompts are answered by default; ask leaves them for the app to show.

• CocoaPods projects build too: pod install runs first when the pods differ from Podfile.lock, keeping its versions. XcodeGen projects are regenerated from project.yml.

• Expo, React Native, Flutter and Capacitor apps: build the Simulator .app with their own tools, then install it with phone_app_control.

3. Run the tests

MCP call

phone_tests_run  { "scheme": "App", "only": "AppTests/SignInTests" }

XCTest and XCUITest, read from Xcode's result bundle: the counts, and each failure as file:line. "0 tests ran" is an error, not a pass. only picks tests, separated by commas.

A build fails on the phone as it would on your Mac, so read its file:line errors first. phone_app_logs shows what the app printed, and with crashes, its crash reports.

In CI

Terminal

simulator-use cloud run . --tests

One line: a phone starts, the project is built, run and tested, a screenshot and a recording are saved, and the phone stops. On GitHub, the simulator-use Action does the same on any runner and posts the result on the pull request.