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",
      "bundle_id": "com.acme.mobile",
      "build": "npm run ios:build"
    }
  ]
}

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 or not_found.

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}"

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.