Your app on a real
iOS Simulator
running on the cloud.

The flow

What native-sim up does.

One command, but the order matters more than it looks — GitHub imposes constraints that shape every step.

1. Local

   Commit and push your app

   Creates the GitHub repo if there isn't one. Your app goes up first, on its own.

2. Local

   Then push the workflow, separately

   A second commit adds .github/workflows/native-sim.yml and the auth gate.

   Why two pushes? GitHub does not scan the first push to a brand-new empty repo for workflow files. Ship the workflow in that push and Actions never registers it — the dispatch then fails with a confusing 404.

3. Local

   Wait for Actions to register it

   Polls until GitHub acknowledges the workflow, and nudges it with a fresh commit if it stalls. A workflow only becomes dispatchable once it exists on the default branch.

4. Local

   Mint a session id and an access key

   24 random bytes. The key is generated here and never leaves your machine.

5. Runner

   Boot, build, install, launch

   A macOS runner boots a simulator, restores the fingerprint-matched build cache or compiles, then installs and launches your app.

6. Runner

   Publish the URL as a commit status

   The tunnel opens and the runner writes its hostname to a commit status.

   Why a commit status? It is the only GitHub surface readable while a job is still running. Logs, artifacts and step summaries only appear after the job ends — far too late for a live stream. The runner publishes the bare hostname only; on a public repo, statuses are world-readable.

7. Local

   Poll, assemble, open

   The CLI polls for that status, appends the key it generated in step 4, and opens your browser. The full link exists only on your machine.

Everything after that is the runner refusing to exit — a health-check loop holds the VM open for --minutes, and the session ends when it stops.

How it works

No inbound ports. No tricks.

A GitHub runner has no public IP and nothing can connect to it. native-sim never needs to — three ordinary mechanisms are stacked instead.

1. A job that refuses to exit

   The final step spends its life in a health-check loop. That loop is the hosting: while it spins, the VM exists and the simulator stays booted.

2. A tunnel dialed from the inside

   cloudflared runs in the job and opens an outbound connection to Cloudflare's edge. Your browser's request comes back down a pipe the runner already opened.

3. One HTTP response that never ends

   The simulator's GPU framebuffer is captured, JPEG-encoded, and written as multipart/x-mixed-replace — a single response that simply never completes.

4. Input travels back over a WebSocket

   Taps and keystrokes reach simctl as genuine touch events. An auth gate re-checks the key on the upgrade request, not just on page load.

Agent control

Let your agent drive it.

--agent runs an agent-device proxy beside the simulator, on the same tunnel and the same key as the stream. Your coding agent taps, scrolls and reads the accessibility tree of an app running on a GitHub runner — while you watch the same session in a browser.

$ native-sim up --public --agent

$ agent-device connect proxy \
    --daemon-base-url https://<tunnel>/agent-device \
    --daemon-auth-token <key>

$ agent-device open com.your.app --platform ios
Opened: com.your.app
Session state: /Users/runner/.agent-device/sessions/proxy_adc-e8554d

$ agent-device press 'label="Explore"' --settle
Tapped label="Explore" (244, 822)
settled after 1003ms: +15 -10 (~5 unchanged)

That /Users/runner/ path is the giveaway — the session lives on the runner, and the coordinates are real touch injections, not screenshot diffing.

Build caching

The build is the whole cost.

A cold native build measured 28.4 minutes. native-sim caches the built .app keyed on @expo/fingerprint, which hashes only what affects the native build and deliberately ignores your JavaScript. Change JS, get a cache hit: the cached native shell is re-bundled with your current code.

Already have a simulator build? --app-file skips compiling entirely, and your source is never pushed — the repo holds only the workflow.

Build hosting

Your builds stay on your repo.

To run a prebuilt app, the runner has to fetch it from somewhere. native-sim uploads it as an asset on a draft release of the same repo the workflow runs in — so the job's own GITHUB_TOKEN can already read it.

$ native-sim up --app-file ./MyApp.app

› Uploading ./MyApp.app to you/your-app
✓ uploaded 26.4 MB as MyApp.app.tar.gz
› draft release on this repo — only people who can read the repo can fetch it

  ● Simulator is live

Cost

Free on public repos.

Limits

What it is not.