lease-and-drive-a-sim
Skill22 starsChanged 3 months agoApache-2.0View on GitHub
Drive an iOS simulator through a manzanasd daemon - acquire a lease, boot, dispatch composite/batch actions, observe/wait_for_element, screenshot, and release with reset. Use whenever a task needs to interact with a simulator on a host running manzanasd instead of raw ssh+simctl+AXe.
- Sends data out
In this repository8 other files it gives its agents.
- broker-federationSkill
- build-and-testSkill
- drive-a-mirrored-iphoneSkill
- journal-evidence-exportSkill
- park-thaw-semanticsSkill
- run-evalsSkill
- run-the-daemonSkill
- ui-audit-and-predicatesSkill
The file
Files
Lease and drive a simulator
Talk to the daemon over HTTP (default port :7433). Every mutating op needs an
active lease; the lease ID is the capability token — never share it.
1. Find a target and acquire a lease
D=http://<mac-tailnet-ip>:7433
curl -s $D/v0/healthz # {"ok":true,"version":"v0"}
curl -s $D/v0/targets | jq '.targets[] | {udid,name,state,labels}'Acquire by label (preferred — pins reset policy to a device class, not someone
else's sim). reset:"erase" guarantees the NEXT holder gets a clean target:
L=$(curl -s -X POST $D/v0/leases -d '{
"labels":["iphone-air"], "agent_id":"<caller-identity>",
"purpose":"<task>", "ttl_seconds":900, "reset":"erase"}')
LID=$(echo "$L" | jq -r .id); UDID=$(echo "$L" | jq -r .target_udid)agent_id is the canonical caller-identity field (a session ID is a fine
value for it); the API also accepts session_id as an alias that fills
agent_id when it is empty. Omitting both is 400 bad_request.
201+state:"active"→ proceed.202+state:"queued"→ pollGET /v0/leases/$LIDuntil active (polling keeps your queue slot; queued leases that go unpolled for 30 min are dropped).409 no_match→ no target carries those labels; re-check/v0/targets.- Renew at ~half TTL for long tasks:
POST /v0/leases/$LID/renew. - Interop: other (non-manzanasd) agents coordinate via
/tmp/manzanas_locks/file locks on the Mac — also writesim-<udid>there for the lease's duration and remove it when done.
2. Boot (asynchronous, gated)
curl -s -X POST $D/v0/targets/$UDID/boot -d "{\"lease_id\":\"$LID\"}" # 202
# poll until Booted:
curl -s $D/v0/targets | jq -r ".targets[] | select(.udid==\"$UDID\").state"503 {"code":"overloaded"} means a host safety gate refused the boot (running
sim cap, load > 2x cores, or <5 GiB free disk) — back off and retry, or use
another host. Do NOT bypass with raw simctl boot.
3. Act — prefer composite + batch (fewer round trips)
Single action: POST /v0/actions with the envelope
{"lease_id":"lse_…","kind":"tap_element","payload":{"label":"Continue"}} —
exactly those three top-level keys; per-kind fields go inside payload,
and per-kind results come back inside result (see PROTOCOL.md §5).
Batch (max 32, strictly ordered, 5-min budget):
curl -s -X POST $D/v0/actions:batch -d "{
\"lease_id\":\"$LID\", \"stop_on_error\":true, \"actions\":[
{\"kind\":\"launch_app\",\"payload\":{\"bundle_id\":\"com.apple.Preferences\",\"terminate_running\":true}},
{\"kind\":\"wait_for_element\",\"payload\":{\"label\":\"General\",\"timeout_ms\":30000}},
{\"kind\":\"tap_element\",\"payload\":{\"label\":\"General\"}},
{\"kind\":\"wait_tree_stable\",\"payload\":{}}]}"tap_element/type_into_elementare composite: they poll the a11y tree for the predicate (label/role/value/id, substring unlessexact:true) and tap the match's centre — use them instead of observe→compute→tap round trips.wait_for_element/wait_tree_stableare the sync primitives; never sleep-and-hope. Both return408 timeoutwhen the budget runs out.observereturns the compacted tree + a stablehash(cheap change detection). Tap a node atx + w/2, y + h/2.- Errors:
410 lease_expired(renew earlier next time),409 target_not_booted(boot first),503 unavailable(AXe/a11y bridge not ready — retry later),400 bad_request(bad payload).
4. Screenshot — request JPEG + max_dim to keep bytes small
curl -s -X POST $D/v0/actions -d "{\"lease_id\":\"$LID\",\"kind\":\"screenshot\",
\"payload\":{\"format\":\"jpeg\",\"max_dim\":800,\"quality\":80}}" \
| jq -r .result.jpeg_base64 | base64 -d > shot.jpgThe base64 image sits inside the action result envelope —
result.jpeg_base64 (or result.png_base64 for PNG), never top-level.
A full-res PNG is several MB; jpeg+max_dim:800 is tens of KB. With the
journal enabled, inline:false skips the base64 in the response — fetch the
capture from the journal artifact instead (see journal-evidence-export skill).
5. Release — always, even on failure
curl -s -X DELETE $D/v0/leases/$LID # idempotentRelease triggers the auto-reset you asked for at acquire (target held, erased, left Shutdown, then handed to the queue). Don't shut the sim down yourself first — the daemon owns post-lease state.
CLI equivalent
manzanas (built by make build) maps 1:1 onto the protocol:
manzanas --daemon $D targets
manzanas --daemon $D lease acquire --labels iphone-air --agent me
manzanas --daemon $D screenshot --lease $LID -o shot.png
manzanas --daemon $D --help # full command listDoes it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

