Modules: daemon, gateway.
Contract: src/contract/operations-leases.ts deviceExec — role agent, effect write.
Input (strict): { leaseId, tool, args, stdin?, stdinFile?, requesterId? }. Output: { exitCode }.
Runs the command on the machine that owns the device and streams its output back.
simlock/clientexecover the socket.simlock simctl|adbuses it only when the daemon is a gateway, on--lease <id>or the caller's one lease. Against a worker the CLI asksdriver.passthroughfor the command and spawns it itself, with its own terminal.- The MCP tool
run_on_device(mcp): the sameexecon the session's held lease, which the caller never names. - HTTP
POST /v1/leases/{id}/exec→ SSE:output, thenexitorerror. The requester is the token's; only anoperatortoken may sendrequesterId. Every failure before the process exists is a plain JSON error with its status; after it, the stream is committed (200) and a timeout arrives aserror.
- Pipeline —
runDispatch(src/daemon/dispatch.ts): parse → role →authorize→ park on readiness → handler. - Authorize — once, at the start:
agentsession:requesterIdpresent →FORBIDDEN; principal must equal the lease'sownerId.adminsession: no bypass.requesterId ?? principalmust equal the lease'srequesterId.- An unknown lease passes; the handler answers
UNKNOWN_LEASE.
- Lease and device from the
Registrysnapshot (Dispatcherdevice.exec). - Resolve —
DriverCatalog.passthrough(tool, device, args, { hasTerminal: false, platform }). The first driver whosepassthroughToolslists the tool answers; none →UNKNOWN_PASSTHROUGH_TOOL. A refusal →PASSTHROUGH_REFUSED. The driver fills the lease's device into the command, and refuses one that names another device (ADR 0047), see "Resolution per platform". - Env —
execBaseEnvironment(process.env)(src/daemon/exec-env.ts, the allowlisted keys, read once at start) + the command'senv, minus itsunsetEnv. - Spawn —
ProcessRunner.spawnStreaming, pipes only, with the lease's folder (LeaseFiles.folderOf) ascwd.stdin(at most 8 MiB of characters, refusedBAD_REQUESTby the contract before any dispatcher forwards or spawns) is written once, then closed.stdinFileinstead names a file of that folder, opened first (UNKNOWN_FILEbefore anything starts) and piped asinputStream; both together areBAD_REQUEST, checked by the worker's dispatcher. A read failure rejects the handle'sinputFailed: the command is stopped as a timeout stops it and the stream ends withSTDIN_FILE_FAILED. A gateway forwardsstdinFileunchanged. startedpush the moment the process exists, then oneoutputpush per chunk ({ requestId, stream, chunk }). The push write is awaited before the child is read again: a slow reader slows the command. Nothing is buffered; no size cap.- Wait, raced against
exec.timeoutMs(10 min). Exit first →{ exitCode }. Timeout first → SIGTERM, SIGKILL after 10 s, answerEXEC_TIMEOUT.
| Tool | Device | Command | Refused |
|---|---|---|---|
simctl |
iOS simulator | xcrun simctl --set <device root> <args> (no --set under drivers.ios.deviceSet: default); the lease's UDID goes first among the operands of a device verb (src/drivers/ios/simctl-device.ts) |
another UDID or booted on a device verb, simctl on a non-iOS lease, create, erase, delete, shutdown all, runtime delete, any flag before the subcommand, a physical device |
devicectl |
iOS physical | xcrun devicectl <cmd> --device <udid> <rest>; --device added unless the args name one; a --device / -d that is not the lease's UDID is refused |
a command not on the allowed list (src/drivers/ios/devicectl-exec.ts), an option off it, host-path options (--json-output, --log-output, --destination, --file, --filter), a simulator |
adb |
Android emulator | adb -P <simlock port> -s <serial> <args>, ANDROID_ADB_SERVER_PORT set; no -s for a no-device subcommand (devices, version, forward --list, …) or an empty address |
-s other than the lease's serial, -t whatever it names, -e, -d, adb on a non-Android lease, bare adb shell, kill-server, disconnect, emu kill, emu avd stop, every emu avd snapshot except list, globals other than -s/-t/-d/-e |
adb |
Android physical | adb -P <default port> -s <serial> <args>; strips ANDROID_ADB_SERVER_ADDRESS, ADB_SERVER_SOCKET, ANDROID_SERIAL |
bare adb shell, any leading flag, server and transport verbs (kill-server, connect, tcpip, usb, …), reboot bootloader/sideload, a closed default-server gate |
A bare adb shell is refused only here (hasTerminal: false); the local
simlock adb shell stays interactive. For simctl and adb the daemon parses
no argument beyond these lists; the driver (not the daemon) fills in and checks the device.
- Pipeline —
GatewayDispatcherruns the samerunDispatch;authorizereadsFleetLeaseIndexinstead of a registry. Nothing parks. FleetLeaseCoordinator.exec: unknown gateway lease →UNKNOWN_LEASE; worker not connected →WORKER_UNREACHABLE.- Forward over the uplink with the worker's lease id and
requesterId: gw:<gateway instance id>:<lease's requester>. The worker checks it again as anadminsession (worker step 2). Two hops, two checks. - Relay the worker's
startedandoutputpushes unchanged. The gateway parses nothing about the command. - Backstop:
gateway.execTimeoutMs(11 min) →EXEC_TIMEOUTnaming the worker. It fires only when the worker never answers; the worker's own 10 min fires first. After it, late chunks are dropped; the worker's command is not cancelled.
A closed connection only stops the pushes (DaemonServer). The command runs on
to its exit or its timeout; the exit code is lost with the connection. A
gateway that gives up the same way leaves the worker's command running.
- Authorized once, at the start. A command still running when its lease ends
keeps running, maybe against a device reclaimed and granted again. Bounded by
exec.timeoutMsand byreclaimingcoming first; refused verbs stay refused. - An
agenttoken on a worker is a host-level credential. Commands run as the daemon's uid (simctl spawnruns any program on the host);adb pull <device path> <host path>writes any path the daemon can. Arguments are an accident boundary, not a security boundary. Only the env is trimmed to the allowlist. - No files. Paths resolve on the worker:
simctl install /tmp/App.appfails with the tool's own "no such file". Ship artifacts out of band;device.uploadis an idea, not built. - No pseudo-terminal. Line-oriented commands work; full-screen or prompting
ones hang until
exec.timeoutMs, thenEXEC_TIMEOUT. Only bareadb shellis refused up front. Locally,simlock adb shellkeeps its terminal.