Enable cloud agents to build and test iOS apps from Linux
A cloud coding agent can edit your iOS app from a Linux VM or container. To check its work, it also needs to compile the app, run it in a simulator, and inspect what happens. Limrun gives the agent access to remote Xcode builds and iOS simulators through skills you add to your repository.
The agent stays in its existing environment. It edits source code and iterates on remote builds, then attaches a simulator when it is ready to test. Your development backend can stay in the agent's Linux environment too. A tunnel lets the simulator reach that backend at localhost:8080.
When the agent opens a pull request, it can include a recorded test session with the app's logs, the actions it took, and the network requests made during testing. It can also upload the PR's app bundle and generate a browser preview link. Your CEO, product manager, and other teammates can watch the test session or launch the app and try it themselves, with no local development setup.
Add the skills to your repository
For an iOS project built with xcodebuild, add the Limrun build and simulator skills from your repository root:
npx skills add limrun-inc/skills \
--skill limrun-xcode limrun-ios-simulator
Choose a project installation for your agent and commit the installed skill files. The build skill teaches the agent to compile through Limrun; the simulator skill teaches it to inspect and interact with the running app. For a Bazel project, use limrun-xcode-bazel in place of limrun-xcode.
Devin, for example, discovers skills committed to your repository, including files under .agents/skills/<skill-name>/SKILL.md. Its Linux environment can keep hosting the checkout, editor tools, and backend while Limrun runs the Apple tools remotely.
The agent needs Node.js and the Limrun CLI in that environment:
npm install --global lim
Provide LIM_API_KEY through your agent platform's environment secrets. The skills are the reusable instructions; the CLI and key give the agent access to the remote builds and simulators. It does not need Xcode or a local simulator installed in its Linux VM or container.
You can then give the agent a task such as:
Fix the checkout retry flow. Use the Limrun skills to build the iOS app and iterate until it compiles. Attach a simulator when you are ready to test. Run our backend on port 8080 and tunnel the simulator to it. Test the failed-request and retry paths, and persist the recording, app logs, event log, and network capture. Upload a browser preview build using our staging backend. Include both the recorded session and the interactive preview link in your pull request.
The following sections show the development loop behind that request. The commands run in the agent's Linux environment, from the same repository checkout and shell.
Iterate on builds first
The agent edits the project, then runs:
lim xcode build .
On the first run, the CLI creates an Xcode sandbox, syncs the source, and invokes xcodebuild on a cloud Mac. Build logs stream back to the agent. It reads compiler errors, changes the source, and runs the same command again. Subsequent builds reuse the sandbox, and source sync sends changed bytes only.
There is no simulator to manage during this part of the task. The agent can work through compilation failures before starting an interactive test session. If project discovery is ambiguous, it selects the scheme and workspace or project using the options in the Xcode build guide.
| Part of the workflow | Where it runs |
|---|---|
| Agent, source edits, and development backend | The agent's Linux VM or container |
| Xcode build | A Limrun Xcode sandbox on a cloud Mac |
| App interaction | A Limrun iOS simulator, attached for testing |
| Review of recorded evidence | The Limrun session page linked from the PR |
| Hands-on review by teammates | A fresh simulator launched from the PR's browser preview link |
Attach a simulator for testing
Once the build succeeds, the agent attaches a simulator to the build sandbox. Replace com.example.checkout with the app's bundle ID:
APP_BUNDLE_ID=com.example.checkout
lim ios create --attach --no-open \
--events --app-logs "$APP_BUNDLE_ID" --persist-ttl 72h
Attaching installs the sandbox's latest successful build without compiling it again. The command also starts persisted event and app log captures. The CLI automatically selects the most recently created simulator in the current workspace for subsequent commands.
The agent can now inspect the app, test a change, and return to its editor if something fails. Each later successful build on the attached sandbox automatically reinstalls the app on this simulator.
Connect the simulator to the agent's backend
Suppose the app's development configuration calls http://localhost:8080, and the agent has started your backend on port 8080 inside its Linux VM or container. From that same environment, it starts a destination tunnel:
lim ios tunnel --selector localhost:8080 --persist --detach
The simulator's connections to localhost:8080 now reach the service on the machine running the CLI. The app keeps using its development URL. --detach leaves the tunnel running so the agent can continue issuing commands.
--persist saves the tunnel's inspected HTTP requests and responses as a network log for the session. The capture includes request and response bodies, subject to body-size limits, and is available as a HAR download. It covers traffic through the selected destination, rather than every packet from the simulator. Add selectors for other backend destinations you need to reach and inspect.
Start recording, then relaunch the app so its connections use the tunnel and its startup logs enter the capture:
lim ios record start --persist --persist-ttl 72h
lim ios launch-app "$APP_BUNDLE_ID" \
--mode RelaunchIfRunning --detach
For HTTPS destinations, tunnel inspection uses a certificate trusted by the simulator. Apps that pin server certificates need a testing configuration compatible with inspection. The simulator skill's tunnel instructions cover selectors and inspection options.
Test, inspect, and rebuild
The agent reads the current screen before deciding what to do:
lim ios element-tree
For the checkout example, it puts the backend into the failure condition required by the test, checks the app's error state, and exercises the retry path. If the element tree contains a button labeled Retry, it can tap it and inspect the result:
lim ios tap-element --ax-label Retry
lim ios element-tree
lim ios app-log "$APP_BUNDLE_ID"
The agent compares the resulting UI with the expected behavior, checks app logs, and inspects the network requests. That gives it evidence to distinguish a UI problem from an unexpected backend response. It can edit the code, rebuild with lim xcode build ., and repeat the interaction on the attached simulator.
The captures serve different purposes:
- The recording shows the app's visible behavior.
- The event log records simulator interactions and commands.
- The app log captures the application's output.
- The network log records inspected requests and responses through the tunnel.
A successful build is one checkpoint. The agent still needs to verify the behavior requested in the task and report anything it could not test.
Publish a browser preview for your teammates
The recording shows what the agent tested. A browser preview lets people explore the PR's app themselves. Opening the preview link creates a fresh simulator with the uploaded bundle pre-installed, ready to use in the browser. Organization members can test a flow without a Mac, Xcode, or the repository on their laptops.
Before publishing, configure the preview build to use a backend reachable by those fresh simulators, such as your shared staging service. The agent's localhost:8080 tunnel belongs to its test simulator and does not transfer to new preview instances.
After committing the final changes, the agent builds and uploads the preview before deleting its Xcode sandbox. This example names the asset for project checkout, PR 482, and commit a1b2c3d:
lim xcode build . --upload checkout-pr-482-a1b2c3d.zip
The asset name includes the commit so reviewers can identify the version they are trying. Build uploads expire after 14 days by default; the PR preview guide covers retention and automating previews in CI.
Link the recording and preview in the pull request
Once testing and the preview upload are complete, the agent stops the recording and tunnel, then terminates its simulator and build sandbox:
lim ios record stop -o checkout-review.mp4
lim ios tunnel stop
lim ios delete
lim xcode delete
Stopping the recording and tunnel finalizes their persisted captures. Terminating the simulator finalizes the app and event logs. Both delete commands use the current workspace to select their instances automatically.
The agent checks that the persisted artifacts and preview are available, then includes both links in its PR description:
[Recorded iOS test session](https://console.limrun.com/sessions/ios/INSTANCE_ID)
[Try the PR build in your browser](https://console.limrun.com/preview?asset=checkout-pr-482-a1b2c3d.zip&platform=ios)
It replaces INSTANCE_ID with the test simulator's ID and uses the uploaded asset's name in the preview link.
The session page brings the recording, app logs, event log, and captured network requests together. These captures outlive the simulator, with a 72-hour retention period in this example. Link the session page instead of a short-lived artifact download URL.
Both links require reviewers to sign in with access to the owning Limrun organization. The CEO can try the checkout flow, a PM can check the interaction, and an engineer can inspect the recorded requests. The uploaded preview remains available after the agent deletes its own simulator, until the asset expires.
Alongside the links, the agent should name the tested commit, describe the failure and retry scenarios it exercised, and state the observed results. It should also identify the backend used by the preview so reviewers know which environment they are testing.
Adding the skills gives a cloud agent a way to carry an iOS change through compilation, testing against its own backend, and review. The PR gives your team the code change, evidence of the agent's tests, and an app they can use in their browser.