Cloud agents + MobAI = iOS development

What you need

For previews and builds: nothing but the setup command below. No API key, no Tailscale, no Mac. Simulators need a free MobAI account; when the agent signs in with your email, the account is created on the spot.

For your own phone, and for over-the-air installs on it:

• The MobAI desktop app on macOS, Windows or Linux, for the one-time phone setup. Download.
• An iPhone on iOS 17 or later, connected by cable during that setup.
• Tailscale on the phone, connected to the same tailnet the sandbox joins.

Claude Code

Open the cloud environment's settings and set its Setup script to:

curl -fsSL https://mobai.run/cloud/install.sh | sh

In the same dialog, add this to Environment variables:

MOBAI_ACCOUNT_EMAIL=<your mobai account email>

Claude Code's environment variables are visible to everyone using the environment, and they are absent while the setup script runs. Do not put API keys, Tailscale keys or signing credentials there. The script installs tools only. In the chat, the agent signs you in with an emailed code; for phone access it also gives you a Tailscale login link to approve.

Network access: new environments start on Trusted, which only reaches an allowlist. Set it to Full.

Cursor

Cursor builds the environment from a Dockerfile in your repository, so the fastest start is the prebuilt image, with Swift, Flutter, Node, the preview engines and mobai-dev already in it. Commit these two files to your default branch:

# .cursor/Dockerfile
FROM ghcr.io/mobai-app/mobai-dev:1.3.1

// .cursor/environment.json
{
  "build": { "dockerfile": "Dockerfile" },
  "install": "curl -fsSL https://mobai.run/cloud/install.sh | sh",
  "start": "$HOME/.mobai/bin/mobai-up"
}

The files alone change nothing until Cursor has built them. In the Cloud Agents dashboard:

1. Create a new environment and select the repository.
2. Click Skip & Save (not the agent setup, which installs onto Cursor's stock Ubuntu and ignores the Dockerfile).
3. Open the environment and click Trigger New Build, with Draft build off. Cursor pulls the image, runs the install command and saves the result.
4. Agents started after that build run in the image. In one, echo $FLUTTER_ROOT prints /opt/flutter; empty means the agent is still on the stock image.

Without the image, leave the Dockerfile out and set only the install command in .cursor/environment.json:

curl -fsSL https://mobai.run/cloud/install.sh | sh

Either way, add these as secrets in the Cursor dashboard, under Cloud Agents, Secrets tab. Scope them to the environment above so only its agents get them; Cursor hands each one to the agent as an environment variable:

MOBAI_API_KEY=<your mobai API key>
MOBAI_TAILSCALE_KEY=<tailscale ephemeral auth key>
MOBAI_ACCOUNT_EMAIL=<your mobai account email>

The email identifies your account, the API key authenticates the sandbox, and the Tailscale key is only needed for your phone. Without an API key the agent signs in with an emailed code; without a Tailscale key it gives you a login link to approve when phone access is wanted. To ship to TestFlight or the App Store from the agent, add the App Store Connect key the same way: ASC_ISSUER_ID, ASC_KEY_ID and ASC_PRIVATE_KEY.

Network access: Cursor allows all traffic by default. Keep it that way. If you turned filtering on, turn it off for this environment.

Codex

In the environment settings, set the setup script to:

curl -fsSL https://mobai.run/cloud/install.sh | sh

Add these values to the environment's secrets:

MOBAI_API_KEY=<your mobai API key>
MOBAI_ACCOUNT_EMAIL=<your mobai account email>

The API key is optional if you sign in during the session with an emailed code. MOBAI_TAILSCALE_KEY is accepted the same way as on Cursor.

Your phone is not reachable from Codex yet. Its sandbox blocks the connection a tailnet join needs, and a Tailscale key does not change that. The script installs Tailscale and tries anyway, so nothing needs re-pasting the day Codex allows it, and the agent is told why the join fails. Previews, builds and simulators work. Use Claude Code or Cursor when the phone is the point.

Network access: Codex filters outbound traffic by default. Set the environment's internet access to full. The tailnet restriction is separate from that setting.

Grok bot

Grok has no setup command field. Paste the same setup command into the chat and the bot runs it in its sandbox:

curl -fsSL https://mobai.run/cloud/install.sh | sh

No environment variables needed. The agent signs in from the chat with an emailed code.

First session

Open a session in your project and say:

Set up the MobAI preview for this project and show me the main screen.

The agent runs the project setup, installs any missing preview engine, starts the preview and comes back with a screenshot. If a sign-in is needed it asks for an emailed code:

mobai-dev login --email you@example.com
mobai-dev login --email you@example.com --code <code>

Signing in is free and creates the account when the email is new. From there, ask for the next thing:

• Show the paywall in dark mode.
• Test onboarding with location permission denied.
• Build the iOS app.
• Run this version on a simulator.
• Install it on my phone and tap through onboarding.

2. Build

iOS builds run on a macOS runner in your own CI. GitHub Actions is the default; Codemagic and Bitrise are one flag away. Set a project up for GitHub Actions and build:

mobai-dev build init
mobai-dev build --ios

Or on a configured provider:

mobai-dev build --ios --provider codemagic
mobai-dev build --ios --provider bitrise

The command pushes a snapshot of the working tree, uncommitted changes included, to your GitHub repository. The selected provider builds that snapshot, and the agent gets the artifact, normally under ./build/. Without --provider the command uses the provider in builder.json, then GitHub Actions.

Use one provider, or set up all three and stack the free minutes each gives you. Builds are free in MobAI; runner time belongs to your CI account. The setup per provider is in CI providers.

Android builds run in the sandbox itself when the Android toolchain is present: mobai-dev build --android.

3. Simulator

Start a simulator running the project:

mobai-dev sim start
mobai-dev sim start --provider codemagic
mobai-dev sim start --duration 30m

The CI runner builds the working tree, boots an iOS simulator, installs the build and publishes the simulator to your MobAI account. The agent receives a device id and takes it from there: live screen, taps, typing, flows, tests. You can watch and take over from the MobAI desktop app.

The provider needs MOBAI_API_KEY in its secret store to publish the simulator. The default idle window is 30 minutes; Codemagic and Bitrise cap it at 60. An unused simulator ends when its window runs out, or earlier with:

mobai-dev sim stop

4. Your own device

After the one-time phone setup, the agent installs a signed build on the iPhone on your desk and drives it from the sandbox over your own tailnet. Your Mac can be off. Before device work the agent brings the session up:

~/.mobai/bin/mobai-up

It handles the MobAI sign-in, joins the tailnet and starts device discovery. A reachable phone appears in the device list within about a minute:

mobai devices
mobai app install ./build/App.ipa
mobai bridge start
mobai observe
mobai screenshot --path /tmp

The agent sees the phone's UI tree and screenshots. It launches apps, taps, types, scrolls and runs complete test flows, as if the phone were plugged into the sandbox.

Install over the air, without the bridge

A signed build can also go onto the phone with nothing running on it:

mobai-dev ota App.ipa
mobai-dev ota stop

The command checks the build's provisioning profile against your onboarded phones before serving anything, then serves the build and an itms-services install link over your tailnet. Open the link on the iPhone and tap Install. If Tailscale Serve approval or HTTPS certificates are missing, the command names the setting and the next step. This installs the app only; driving it still needs the bridge.

Signing

A physical iPhone needs a signed build whose provisioning profile includes that phone's UDID. Signing also decides how long the bridge on the phone stays usable:

• Paid Apple Developer account: a year.
• Free Apple ID: seven days. Reconnect the phone and repeat step 2 of the wizard.

There are two sets of signing secrets, for two different jobs:

• IOS_*_<SET> in the repository: the macOS CI runner signs your app build with them. A signed mobai-dev build or mobai-dev release needs these.
• MOBAI_SIGN_* in the agent's sandbox: a phone session signs the bridge (and the apps it installs) itself, so the phone stays ready without your Mac. This needs a wildcard profile, so it is made by hand.

Set up once: ios-builder (recommended)

Signing for a repository is set up once, by you, on your own machine: agent sandboxes usually cannot write repository secrets (Cursor's cannot). The quickest way is the desktop app: Integrations > Cloud Agents > Sign builds (also the optional last step of the cloud wizard). Sign in to GitHub, pick the repository, choose development and/or TestFlight, and it creates the certificate and profile with your App Store Connect key, writes the secrets and commits builder.json; the private key stays on your computer, and a year later the same panel renews the set. The same thing from a terminal: builder, the ios-builder CLI, does the Apple side with an App Store Connect API key, uploads the secrets and writes the build profile:

# install: macOS, Linux, WSL
curl -sSL https://raw.githubusercontent.com/MobAI-App/ios-builder/main/install.sh | bash
# Windows: builder-windows-amd64.exe from github.com/MobAI-App/ios-builder/releases,
# renamed to builder.exe and put on PATH

builder auth github      # once
builder auth apple       # once, the App Store Connect API key

# in the repo, once per app (and again with --distribution store for TestFlight)
builder signing setup --distribution development --device <udid> --yes \
  --out-dir ~/.mobai/signing/myapp
git add builder.json && git commit -m "signing profile" && git push

# the agent, every time
mobai-dev build --ios --profile development

It registers the phone, creates the bundle ID if it is missing, has Apple issue a certificate from a private key made on your machine, creates the profile and uploads four repository secrets: IOS_CERTIFICATE_DEVELOPMENT, IOS_CERTIFICATE_PASSWORD_DEVELOPMENT, IOS_PROVISIONING_PROFILE_DEVELOPMENT and IOS_EXTENSION_PROFILES_DEVELOPMENT. Then it writes a development profile and ios.bundleId into builder.json. The profile is written only when the secrets were uploaded, so a profile in builder.json means the repository can sign. Running it again reuses what is still valid. It never revokes anything.

• Keep the key out of the repo. Without --out-dir, the private key, the .p12 and the .mobileprovision are written to the current directory, which is your repo. Keep that folder: later runs find the key there and reuse its certificate. Leave signing.dir out of the commit: it is that path on your machine.
• Apple caps certificates per team. When the team already holds its limit, Apple answers 409, "You already have a current Development certificate or a pending certificate request". Revoke one you no longer use in the developer portal, or pass --key <path> with the private key of an existing certificate.
• Agents that can write secrets can run mobai-dev signing setup in the sandbox instead. It checks first and creates nothing when the token cannot write the secrets.
• No repository signing, phone only. With the App Store Connect key in the sandbox, mobai-dev signing generate makes a development certificate for that sandbox only and prints how to sign the unsigned build with zsign. Development builds only, never TestFlight.

Manual: developer portal and Keychain

The path for MOBAI_SIGN_*, or when you have no API key. The wizard shows the same steps:

1. Register the phone in the Apple developer portal.
2. Create a wildcard provisioning profile (App ID *) that includes the phone. Wildcard matters: it has to cover both your app and the bridge.
3. In Keychain Access, export your Apple Development certificate as a .p12.
4. Base64 both.

base64 -i profile.mobileprovision | tr -d '\n' | pbcopy
base64 -i identity.p12 | tr -d '\n' | pbcopy

For CI builds, set them as IOS_CERTIFICATE_DEVELOPMENT, IOS_CERTIFICATE_PASSWORD_DEVELOPMENT and IOS_PROVISIONING_PROFILE_DEVELOPMENT in the provider, and add "profiles": {"development": {"distribution": "development"}} to builder.json. For signing inside a phone session, set these in the agent's secret store:

MOBAI_SIGN_PROFILE_B64=<base64 of your .mobileprovision>
MOBAI_SIGN_P12_B64=<base64 of your .p12>
MOBAI_SIGN_P12_PASSWORD=<the p12 password>

With these set and a paid Apple Developer account, sessions keep the phone ready on their own and sign the apps they build. That needs a platform with a secret store and phone access, which today means Cursor. On Claude Code, keep the signing secrets in CI and let the build come out signed there.

Troubleshooting

The agent says there are no devices

An empty list is not an error. The phone may be asleep, off the tailnet or still connecting. Wake it, confirm Tailscale is connected and on the same tailnet as the sandbox; a reachable phone appears within about a minute of the session starting. If it still does not, reconnect the phone to Wi-Fi, toggle Tailscale off and on, and bring the MobAI app on the phone to the front.

Ask the agent to read ~/.mobai/mobai.log. It records which peers were found on the tailnet, what each connection attempt failed on and when it retries. A phone can show as online in Tailscale and still refuse the connection MobAI needs.

On Codex the tailnet join is blocked by the sandbox; retries will not fix it. Continue with a preview or a simulator, or use Claude Code or Cursor for the phone.

The setup script fails on a missing variable

Use the exact command for your platform from this page. Claude Code's script receives no environment variables and needs none; a script that demands them there is the wrong script or an old copy. On Cursor and Codex, check the values sit in the environment's secrets. Without MOBAI_API_KEY, finish the emailed sign-in in the session instead.

Downloads fail partway through

Set network access to full internet and run the setup command again. Release downloads redirect, and package installs reach more hosts than any list anticipates. On Cursor, check whether you turned filtering on; on Claude Code and Codex it is on by default. On Claude Code, the level is called Full.

GitHub Actions cannot be reached

If the agent reports that its GitHub credential cannot use Actions, fix the credential. If the sandbox itself blocks the GitHub API, no token helps: run the workflow from GitHub's web interface, or build on Codemagic or Bitrise, which use their own APIs and only need a git push.

The app will not install on the phone

The build is unsigned, or its provisioning profile does not include the phone's UDID. Run builder signing setup --distribution development --device <udid> --yes on your machine (it registers the phone and renews the profile) and rebuild with --profile development. By hand: register the phone in the Apple developer portal, refresh the profile and update IOS_PROVISIONING_PROFILE_DEVELOPMENT. mobai-dev ota checks both before it serves anything.

It worked yesterday and now it does not

With a free Apple ID the bridge's signing expires after seven days. Connect the phone to your Mac and repeat step 2 of the wizard, Prepare the device.

What is shared

Previews run in your sandbox. Builds and simulators run in your own CI account. Phone traffic goes between the sandbox and your iPhone over your own tailnet. MobAI hosts nothing in that data path.

For each phone you onboard we store its identifier, name, iOS version and an encrypted pairing record, so your sessions can find and connect to it.

Remove a phone from the cloud setup wizard and everything stored for it is deleted. The API key is revoked separately, from API Keys. The binary the sandbox runs is open source: github.com/MobAI-App/mobai-dev.