Device ownership¶
A device that a session holds takes control calls only from that session.
getAndroid, getApple and startDevice acquire a device and return the new
session’s sessionUuid. The session holds the device until it is released.
For refusals, capacity and dropped devices, see Device availability and capacity.
Releasing a session explicitly¶
daemon/releaseSession always succeeds, so releases stay idempotent after a
daemon restart:
| Case | Result |
|---|---|
| This daemon remembers an earlier release | alreadyReleased:true, known:true |
| Unrecognized session | alreadyReleased:false, known:false; with requireKnown:true, refused with daemon_session_not_found |
| Restoration incomplete | cleanup is pending or failed (failure takes precedence); inspect the restore reports before relying on the device |
| Restoration complete | No cleanup field |
Passing the session¶
| Caller | How the session is passed |
|---|---|
| MCP | A connection that acquired a device is bound to it, so its calls route to the session without repeating it. A different connection passes sessionUuid in the call arguments; while the acquiring connection is still connected, that works for reads only. |
| CLI | Each --cli call is its own connection: pass the acquisition’s sessionUuid on every later call, as in auto-mobile --cli --session-uuid <uuid> tapOn --selector '{"text":"Submit"}'. A second --cli getAndroid for the same device reuses the anonymous session. Free the device with --daemon release-session. --daemon heartbeat on a one-shot CLI session is a successful no-op, so keeper processes are unnecessary. |
| Default session | Only setActiveDevice or an acquisition changes the session that untargeted calls run on. An explicit sessionUuid targets that one call only. A call passing only platform runs on the default session when the platform matches. |
deviceId |
observe and the app-management tools (installApp, launchApp, terminateApp, crashApp, appLifecycle, uninstallApp, listApps, setAppPermissions, getAppPermissions, inspectPackageSigning, resetKeychain) take deviceId to pick one of several booted devices: an Android serial such as emulator-5554, or an iOS UDID. |
device |
Not a device id: it is an executePlan device label. A serial passed there is refused with a message that names deviceId. |
If you hold two sessions and the default one ends, a control call that passes the
surviving session’s sessionUuid or deviceId runs on that session. A control
call with only platform, an unmatched deviceId, or no selector gets
no_active_device_session. Call setActiveDevice or acquire a new session.
What is refused¶
A control call on a held device gets device_owned_by_other_session when it:
- carries no
sessionUuid(a plain--cli tapOn, for example); - names a different session than the holder;
- names the holder’s session from another connection while the owner is still connected.
Naming a session’s UUID never takes it over. Once the owner has disconnected (a
finished --cli call, for example), another connection may name the session. A
device that no session holds takes calls from anyone.
Other refusals you may meet, and what to do:
| Code | Meaning and next step |
|---|---|
ambiguous_session_selector |
Several of your sessions match; pass sessionUuid or deviceId. |
ambiguous_device_target |
An unnamed call matched several devices; reads pass deviceId, control calls acquire a session and pass sessionUuid. |
device_outside_bound_session |
The call names a deviceId other than the session’s device. |
read_session_not_bound (not retryable) |
A read named a session another connected client owns. Read on the owning connection, or pass deviceId instead of sessionUuid. |
plan_execution_in_progress (retryable) |
A plan is running; retry when it finishes. Reads stay allowed. |
session_ownership_lost, no_active_device_session |
The session is gone for good (retryable: false, nextAction: "acquire_new_session"). Acquire a new session. |
session_released_during_creation |
The session was released before it finished creating. Acquire a new one. |
daemon_session_suspect (retryable) |
The owner’s heartbeat is late; retry now. |
session_held_by_recovery (retryable) |
Device recovery is in flight; retry after retryAfterMs. |
discovery_incomplete (retryable) |
adb or simctl listing failed, so AutoMobile will not boot or adopt a device blind. Retry. |
registry_schema_unsupported (not retryable) |
A strict ownership read found unknown migrations; dbPath, unknownMigrations and recorded writerVersions identify the registry and builds. Upgrade the daemons sharing it. |
device_owned_by_other_daemon (retryable) |
Another AutoMobile daemon holds the device. Stop it there, wait, or choose another device. |
device_assigned_to_binding |
A broker binding holds the device; use another device. |
Your MCP client may first ask you to resolve ambiguous_device_target; see
Choosing a device. For other daemons, see
Several daemons on one host.
When a refusal carries retryAfterMs, wait that long before retrying.
Refusals do not count as session use and do not extend the session’s idle window.
Reads and control¶
Read-only calls never need a session and never count as activity, even for the holder. Anything that changes visible UI or starts a device-side process is control.
| Kind | Calls |
|---|---|
| Read | observe, snapshotOf, hitTest, identifyInteractions, listApps, getDeviceState, getNetworkGraph, getPreference, listDataStores, getDataStore, getAppPermissions, getNotificationPolicy, getDeepLinks, getNavigationGraph |
| Read (mixed tool, per call) | keyboard detect/list, clipboard get, mediaSession get, displayConfig with no set field, accessibility with no toggle, prototype status/inspect, a single read-only sqlQuery statement |
| Control | The other forms of those mixed tools, plus systemTray, videoRecording and deviceSnapshot |
- A sessionless read without
deviceIduses an already-running device and never boots one. If none is running it answers that there is nothing to read. Start one withstartDeviceorprovisionDevice, or pass adeviceId. - A sessionless read that passes
deviceIdmay boot that stopped device (an Android AVD name or an available iOS simulator UDID). It never creates one, and boot capacity limits still apply. - Ownership is a guard between cooperating clients, not a security boundary against other local processes.
A read that passes the sessionUuid of a session another connected client owns
gets the non-retryable read_session_not_bound, which names the session.
Knowing the UUID is not enough. The exceptions are a broker connection granted
that session and a call that presents the session’s owner token.
- Read on the owning connection, or leave
sessionUuidout and passdeviceIdfor a sessionless read. - Once the owner has disconnected (a finished
--clicall, for example), another connection may read under the session. - A
sessionUuidthat names no device session (such as an IDE observer session) still reads sessionlessly.
When a session is released¶
A session ends on an explicit release, a lost owner heartbeat, the idle window, the owning connection closing, or a killed or lost device. Tune the windows with the variables in Environment variables.
- Lost heartbeat. A session whose owner stops heartbeating ends after roughly ten seconds. Calls from other callers do not keep a dead owner alive.
- No first heartbeat. If the owner has never heartbeated, the session ends about 20 seconds after creation when it set its own heartbeat timeout (about 5 seconds on the default timeout). After that it ends once no control call arrives within its heartbeat timeout.
- Idle. A session ends after 2 minutes (default) with no control call.
Heartbeats and reads do not extend the window. Neither does a
setToolEnabledcall that does not pass the session’ssessionUuid. A control call still running holds the release until it finishes. EveryblePeripheralaction,statusincluded, is a control call and extends it. - Plan labels. A multi-device plan runs its extra labels on derived
<base>:<label>sessions. They live only as long as the plan run and end with the base session. The next plan run mints them again; do not create<base>:<name>sessions yourself.
Terminal releases¶
AutoMobile never revives a released session UUID. A later call naming it gets
session_ownership_lost, retryable: false and
nextAction: "acquire_new_session". A call still running when its session ends
is cut with the same refusal. Extra fields depend on the release:
| Release | Extra field |
|---|---|
| Idle | idle: true |
cli-idle-timeout |
idleTimeoutMs: the AUTOMOBILE_CLI_SESSION_IDLE_TIMEOUT_MS of the last --cli call that used the session, capped at 1 hour |
Derived plan label session ending with its base’s cli-idle-timeout |
The base’s idleTimeoutMs, the window that expired |
Daemon and device restarts¶
A daemon restart is not terminal: the owner reclaims the session under the same
UUID. While the daemon reclaims the binding, calls may get the retryable
binding_ownership_unconfirmed; wait retryAfterMs. If ownership cannot be
confirmed in about a minute, the session ends and calls get
session_ownership_lost.
If the previous daemon crashed or was killed, its sessions wait at most about 8
seconds for their owner to reconnect, whatever their own heartbeat or CLI idle
window. A client that is still running and heartbeating keeps its session;
otherwise the device frees within seconds. A CLI session does not heartbeat, so
its next call gets session_ownership_lost; acquire a new session.
When a device restarts, its session can resume under the same UUID for 180
seconds. Meanwhile other sessions cannot take that device: a start naming it gets
a retry hint. If the window passes without a resume, the session ends with
session_ownership_lost.
Device killed or lost¶
An explicit kill ends the session with session_ownership_lost. While the kill
runs, calls get session_terminal_release_in_progress (retryable: false).
Acquire again under a new session.
With session continuity enabled, a connection loss can instead return
device_lost while AutoMobile keeps the session:
| Field | Meaning |
|---|---|
deviceId |
The lost serial |
replacementDeviceId |
When present, the live replacement |
retry.sameSession: true, requiresNewSession: false |
Retry using the same sessionUuid |
recovery.status: "pending" |
Recovery is still settling, even if a replacement serial is known; wait and retry |
recovery.status: "recovered" |
Recovery completed |
recovery.attempts |
Recorded attempts; zero when only live-session evidence is available |
An exhausted or unattempted recovery keeps its reported status. Follow
sessionState and retry to decide whether to reacquire. Without a retained
session or incident, the response carries no retry guidance.
Verify continuity with the
binding metadata and liveness notification.
The generation counter restarts at zero after a daemon restart. AutoMobile sends session_device_rebound at info
level, so a client that raised its log level above info will not see it; read
session-info instead.
Release reasons¶
| Reason | Terminal? | What the client sees |
|---|---|---|
explicit-release |
Yes | session_ownership_lost; acquire a new session. |
cleanup-expired (legacy: lazy-expiry) |
Yes (idle) | session_ownership_lost refusals and session-not-found answers (heartbeat, daemon/sessionInfo) carry idle: true. Acquire a new session. |
cli-idle-timeout |
Yes (idle) | session_ownership_lost refusals (including the daemon/registerSession refusal) and session-not-found answers (heartbeat, daemon/sessionInfo) carry idle: true and idleTimeoutMs for a one-shot CLI session. |
heartbeat-timeout, missing-first-heartbeat |
Yes | session_ownership_lost, with the heartbeat age and limit in the message. |
rehydration-owner-timeout |
Yes | session_ownership_lost: a rehydrated session’s owner never reclaimed it. |
owner-disconnected |
Yes | session_ownership_lost: the owning connection closed and no other client owns the session. |
binding-ownership-lost |
Yes | session_ownership_lost: another execution took the broker binding and its device; acquire a new session. |
managed-slot-ownership-lost |
Yes | Persisted legacy spelling of binding-ownership-lost; existing rows remain terminal. |
device-killed (also a sessionless stop of the device a handed-off session was waiting for) |
Yes | session_terminal_release_in_progress while the kill runs, then session_ownership_lost. |
device-disconnected:<device> |
Yes | session_ownership_lost: the device was lost. |
identity-recovery-<reason> |
Yes | session_ownership_lost with recoveryReason and deviceId (and ownerPid when another daemon holds the device): restart recovery could not prove the device’s identity. |
session-creation-cancelled |
Yes | session_ownership_lost: the creation was cancelled before the session was handed out. |
daemon-shutdown, daemon-restart |
No | The restarted daemon rehydrates the session; its owner reclaims it under the same UUID. |
restart-recovery-timeout |
Yes | session_ownership_lost, without idle: the device-restart recovery window ended without a resume. Acquire a new session. |
device-restart:<device> |
No | The owner can resume the same UUID within the fixed 180 s recovery window. If it lapses unresumed, the session ends terminally as restart-recovery-timeout; an earlier idle deadline ends it as expired with idle: true. |
superseded |
No | Nothing: a newer incarnation of the same UUID holds the device. |
plan-auto-release |
No | The plan freed a device it acquired; caller-held sessions stay held. Naming the same session UUID in a later plan re-issues the session; another client may take the device in between. It is not rehydrated after a daemon restart. |
session-creation-timeout, allocation-rollback, device-disconnected-during-session-create:<device> |
No | The session was never handed out; the UUID may be created again. |
expired |
No | A non-terminal row past its idle deadline: a control call naming it is refused with session_ownership_lost, reason expired and idle: true; heartbeat and daemon/sessionInfo answer daemon_session_not_found, releaseReason: "expired" and idle: true. |
Stopping a held device: killDevice and deleteDevice¶
Only the holder may stop a device it holds. Stopping a booted device another
session holds gets device_owned_by_other_session, unless the call passes
force: true. Force stops the device and releases the holder. From the CLI:
auto-mobile --cli killDevice --device '{...}' --force true. Use it only when
the device really should be stopped out from under its holder.
- Naming the holder’s
sessionUuidfrom a connection that does not own that session is refused, with or withoutforce. To force-stop the device, leavesessionUuidout. forcenever overrides another session’s device-restart reservation (the refusal is retryable withretryAfterMs) or a broker binding’s device.- A device another live AutoMobile daemon holds gets
device_owned_by_other_daemon. Stop it through that daemon, wait for it to release the device, or passforce: true. - For a wedged Android emulator,
forcealso skips the AVD-name comparison. killDevicestops an Apple Watch simulator too: passplatform: "watchos"and its UDID. It refuses a UDID that is not a watch simulator, and releases the watch’s runner.- A refused
deleteDevicecarries the same typed fields as a refusedkillDevice.
deleteDevice deletes an Apple Watch simulator with target.platform: "watchos"
and the watch’s UDID as target.stableId. It stops a running watch first,
releasing any session on it. It succeeds once a fresh watch listing no longer
shows the watch.
| Result | When |
|---|---|
already_absent |
No watch simulator has that UDID; deletes nothing, even if it names another simulator |
identity_conflict |
target.stableName differs from the watch’s name |
watch_delete_failed |
simctl delete failed |
teardown_deadline_exceeded |
The call ran out of timeoutMs |
Apple simulators¶
How sessions select, start and release Apple TV, Vision Pro and Apple Watch simulators is in Apple simulator sessions.
Streams need an observer registration, not a session¶
subscribe, request_observation, video and WebRTC viewing need a lightweight
observer registration, not a session. Tools need nothing, and streams need only
that registration. A viewer keeps streaming when ownership changes.
Recordings¶
- A recording stops and finalizes within about 120 seconds of its session’s release, idle releases included.
- Recording artifacts stay fetchable by id.
- Hiding a desktop or IDE window during a recording does not release the device.
- A video start from the connection holding a device belongs to that session,
even when the call omits
sessionUuid. - Starting a device gesture recording on an unheld device gets
no_active_device_session; acquire a session on that device first. - An ownerless active recording keeps running when a session acquires its device, and that holder adopts it. Before then anyone can stop it; afterwards only the holder.
Display and system settings between owners¶
AutoMobile does not restore display and system settings when a session releases the device. It resets them when a different session next acquires the device:
- Before a session first changes a setting, AutoMobile records its current value as the device default. It does not record changes made while no session holds the device.
- A different session acquiring the device resets each recorded setting whose value differs from its default. The same session acquiring it again resets nothing. AutoMobile logs a failed reset and retries it at the next acquisition by another session.
| Tool | Covered settings |
|---|---|
displayConfig |
Font scale (content size category on the iOS Simulator), display density, night mode, increase contrast, reduce motion, bold text and Android display accessibility preferences |
changeLocalization |
24-hour format and calendar system |
| iOS Simulator | Device-wide locale (Android locale changes are not covered) |
On Android, displayConfig also sets the runtime screen size, navigation mode
and display-cutout emulation. AutoMobile restores those when the session that
changed them releases the device or rebinds to another one. displayConfig
reset clears a leftover size override even after a daemon restart.
Appearance configuration is per session.
Which read tools ready an unheld device¶
A sessionless read that names a running device nobody holds can set up CtrlProxy (Android) or the runner (iOS simulator) so the read can answer. Yes means the read does that setup. AutoMobile never readies a device another session or daemon holds or reserves: reads use what is already installed, and control is refused.
| Tool | Android | iOS simulator |
|---|---|---|
accessibility |
Yes | Yes |
captureAudio |
No: booted-only verification | No: booted-only verification |
clipboard |
Yes | Yes |
compareScreenshot |
Yes | Yes |
displayConfig |
Yes | Yes |
getAppPermissions |
Yes | Yes |
getDataStore |
Yes | Yes |
getDeepLinks |
Yes | Yes |
getDeviceState |
Yes | Yes |
getLogs |
Yes | Yes |
getNavigationGraph |
Yes | Yes |
getNetworkGraph |
Yes | Yes |
getNotificationPolicy |
Yes | Yes |
getPreference |
Yes | Yes |
hitTest |
Yes | Yes |
identifyInteractions |
Yes | Yes |
inspectPackageSigning |
No: booted-only verification | No: booted-only verification |
keyboard |
Yes | Yes |
listApps |
No: booted-only verification | No: booted-only verification |
listDataStores |
Yes | Yes |
mediaSession |
No: booted-only verification | No: booted-only verification |
observe |
Own path: may start the service (see below) | Own path: may start the service (see below) |
prototype |
Yes | Yes |
snapshotOf |
Yes | Yes |
sqlQuery |
Yes | Yes |
statusBar |
Yes | Yes |
Related¶
- Environment variables: session release and idle windows.
- FAQ.