iOS Simulator

The simulator API is for macOS environments that boot an iOS simulator. Use it to check readiness, connect to live video and control streams, capture screenshots, trigger rebuilds, and read simulator build logs.

The simulator is configured in the environment manifest. It is not created independently through the API.

Configure The Environment

Simulator configuration requires darwin/arm64.

{
  "version": 1,
  "platform": { "os": "darwin/arm64" },
  "sources": [
    {
      "repo": "acme/mobile",
      "workspace": "/Users/admin/workspace/mobile",
      "branch": "main"
    }
  ],
  "setup": [
    {
      "name": "install",
      "run": "npm ci",
      "working_dir": "/Users/admin/workspace/mobile"
    }
  ],
  "simulators": [
    {
      "platform": "ios",
      "device": "iPhone 18 Pro",
      "runtime": "latest",
      "bundle_id": "com.acme.mobile",
      "build": "npm run ios:build"
    }
  ]
}

Set device to an available simulator model. Set runtime to an installed iOS version to pin it, or use latest to select the newest installed iOS runtime that supports the device. Wallfacer checks compatibility when the simulator boots, including after snapshot restore. If no installed runtime supports the device, startup fails with an error naming the device and installed runtime versions. Omitting device uses iPhone 18 Pro unless the deployment configures another device. Omitting runtime uses latest. An unavailable or incompatible pinned version causes simulator creation to fail.

Existing saved iOS simulator entries that named iPhone 17 Pro are updated to the configured device, including entries that stored the former default. Other device selections remain unchanged. See the manifest reference for the device override and macOS image requirement.

Use build for native compile, install, and launch flows. Use run for development-server flows such as React Native or Expo.

Boot A VM Or Session

The simulator becomes available inside a VM booted from that environment. You can boot it directly with the VM API, or indirectly through a coding session.

Direct VM boot:

curl -s -X POST "$WALLFACER_API/accounts/$ACCOUNT_ID/vms" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ios-vm-001" \
  -d '{"environment_id": "'$ENVIRONMENT_ID'"}' \
  | jq ".data"

Wait for the VM to be ready before expecting simulator routes to work.

Read Simulator Status

curl -s "$WALLFACER_API/accounts/$ACCOUNT_ID/vms/$VM_ID/simulator" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  | jq ".data"

The response includes:

If the VM has no active simulator, simulator routes return an error such as no_simulator. A malformed VM ID, missing VM, or VM outside the account returns 404 with errors[].code set to not_found on every simulator route, including logs. Check the account and VM resource UUID before retrying.

Capture A Screenshot

The screenshot endpoint returns PNG bytes directly.

curl -s "$WALLFACER_API/accounts/$ACCOUNT_ID/vms/$VM_ID/simulator/screenshot" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  -o screenshot.png

Use this for automation checks, CI artifacts, or visual debugging.

Trigger A Build

curl -s -X POST "$WALLFACER_API/accounts/$ACCOUNT_ID/vms/$VM_ID/simulator/builds" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  | jq ".data"

The rebuild is asynchronous. Read simulator logs to watch progress.

curl -s "$WALLFACER_API/accounts/$ACCOUNT_ID/vms/$VM_ID/simulator/logs" \
  -H "Authorization: Bearer $WALLFACER_TOKEN" \
  | jq ".data[] | {event, level, created_at}"

If $VM_ID does not identify a VM in the account, the logs request returns 404 with errors[].code set to not_found. Check the account ID and VM resource UUID before retrying.

When To Use Session Messages Instead

Use the simulator API for machine-level actions: status, video/control URLs, screenshot capture, rebuild trigger, and logs.

Use session messages when you want the agent to change code, inspect the UI, or explain what it sees. The simulator API gives you the raw device surface; sessions give you an AI workflow around it.