Run the simulator

The macOS simulator is the normal development host. It runs the same AgentOS supervisor, resident Agent guest, ordinary App source, Tool catalog, workspace contracts and PocketJS Views as both ESP32 hardware compositions while replacing board adapters with macOS implementations.

Start with a persistent workspace

cargo xtask run esp32-sim \
  --backend codex \
  --workspace target/esp32-workspace

The default workspace is target/esp32-sim/workspace. Supplying an explicit path makes test state obvious and lets separate App experiments use separate workspaces. Do not delete the directory if you want installed Apps and SQLite state to survive.

Choose a model backend

OPENAI_API_KEY=... \
  cargo xtask run esp32-sim --backend openai --model gpt-5.6

OPENROUTER_API_KEY=... \
  cargo xtask run esp32-sim \
  --backend openrouter --model openai/gpt-5.6

ANTHROPIC_API_KEY=... \
  cargo xtask run esp32-sim \
  --backend anthropic --model claude-sonnet-4-6

DEEPSEEK_API_KEY=... DEEPSEEK_THINKING_LEVEL=xhigh \
  cargo xtask run esp32-sim --backend deepseek

Backend selection belongs to the host composition. It does not change the resident App, ordinary App contract or Tool definitions.

Open a specific surface

cargo xtask run esp32-sim --backend codex --app files
cargo xtask run esp32-sim --backend codex --app apps
cargo xtask run esp32-sim --backend codex --app settings
cargo xtask run esp32-sim --backend codex --app keyboard

These names start in the corresponding Pi Agent surface. An installed ordinary App id may also be supplied with --app. The default viewport is 720×1280. Use --viewport 800x480 or --viewport 480x800 to exercise the same App source at the S3 panel shape and rotated logical shape. Mouse input follows the same View hit-testing path as touch.

Install an App into the running simulator

cargo xtask package app counter

curl --fail-with-body \
  --data-binary @target/pocketapps/counter.pocketapp \
  http://127.0.0.1:8080/install

The upload returns HTTP 202 and switches the product to the shared review screen. Click INSTALL inside the simulator to activate it. This is the same review and AppSupervisor lifecycle used by the physical HTTP ingress; the transport does not write App state directly.

Generate a deterministic screenshot

cargo xtask snapshot esp32-sim

The output is artifacts/screenshots/esp32-sim.png. For targeted snapshots, invoke the simulator with --screenshot, --app, --promptor --tap x,y through its lower-level Cargo command. The standard xtaskcommand intentionally keeps the common path small.

Simulator fixtures

Exa and Robinhood use deterministic native service fixtures in the simulator. Their real App source, SQLite writes and Views run unchanged, but provider responses are simulated. Use a physical standalone backend for fresh provider and transport acceptance.

Simulator success proves product contracts and macOS adapters. It does not prove ESP-IDF, PSRAM allocation, PPA, LittleFS capacity, NVS, LCD/touch, Wi-Fi or live provider behavior.