Skip to content

Daemon

The AutoMobile daemon is a local background service that keeps a pool of devices ready for work. It assigns a device to each session, proxies the same MCP tools and resources, and returns the device to the pool when work ends.

%%{init: {"flowchart": {"defaultRenderer": "elk"}, "elk": {"keepEntryNodeOnTop": true}} }%%
flowchart LR
  Daemon[🤖 MCP daemon] -->|assign a device| Sessions[📱 Device session manager]
  Sessions -->|start work| Loop
  subgraph Loop[🔄 Interaction loop]
    direction TB
    Device1[📱 Device 1]
    Device2[📱 Device 2]
    More[📱 Device …]
    DeviceN[📱 Device N]
  end
  Loop -->|collect results| Results[🖼️ Processed results]
  Results -->|return to the daemon| Daemon

It can run as a standalone service, within the MCP server, or temporarily in CI, so clients need not manage device processes themselves.

HTTP ingress

Daemon HTTP ingress requires a per-daemon bearer token. Before binding the loopback HTTP listener, the daemon generates a fresh token in memory with randomBytes(32).toString("base64url") (256 random bits). The listener requires that token from its first request. Only after a successful bind does the daemon atomically publish the token file. A failed bind leaves an existing token file unchanged. On POSIX the path is /tmp/auto-mobile-daemon-<uid><isolationSuffix>.token; on Windows it is path.join(process.env.LOCALAPPDATA ?? os.tmpdir(), "auto-mobile", "daemon<isolationSuffix>.token"). AUTOMOBILE_AUX_SOCKET_DIR determines the same isolation suffix as those files; AUTOMOBILE_DAEMON_TOKEN_FILE_PATH overrides the token path and relative overrides resolve against the daemon launch directory. Clean shutdown removes the token file only if it still contains this daemon’s published token.

Every HTTP path and method, including /heartbeat, /auto-mobile/streamable, OPTIONS and unknown paths, requires Authorization: Bearer <token> (the scheme is case-insensitive). Host and Origin checks run first. Missing or invalid credentials return 401, WWW-Authenticate: Bearer, and {"error":"Unauthorized"}. An ingress without a configured token refuses to start.

The listener binds, and its port is discoverable, before the daemon publishes its token at the end of device discovery and session rehydration. A request that passes the Host and Origin checks during that window is held, without evaluating its credentials, until startup finishes (at most 30 seconds), then authenticated. A client still holding a previous daemon’s token then gets 401 and should re-read the token file once and retry. If startup outlives that bound the request gets 503 with Retry-After: 1 and {"error":"Daemon is still starting"}; a failed startup answers 503 with {"error":"Daemon startup failed"}, and a daemon that is shutting down answers 503. Treat a 503 carrying Retry-After as transient and retry it until the caller’s own deadline. Credentials are removed before MCP dispatch and are never included in diagnostics, status, PID records or telemetry.

Local clients read the UTF-8 token file and trim whitespace. On POSIX, the file must be a regular file owned by the current uid with mode 0600; symlinks are refused. Writes use an exclusive 0600 temporary file in the same directory and rename it into place. The parent directory is created with mode 0700 where supported. Windows uses the same publication rules without POSIX uid/mode checks. It retries a rename that fails with a transient sharing violation (EPERM, EBUSY, EACCES) only while the public token file is unchanged since publication began. If another daemon publishes during the backoff, publication fails without overwriting it, and the aborted store never claims ownership (remove() leaves that token alone).

External clients must discover the file using the daemon’s launch environment and read it again after a daemon restart. TypeScript clients can use readDaemonHttpToken(env) or daemonHttpAuthHeaders(endpoint, env). The latter returns the Authorization header only for a daemon endpoint, and {} for any other URL. A daemon endpoint has an exact loopback host (localhost, 127.0.0.1, [::1]), an explicit port in the original URL spelling, and path /auto-mobile/streamable or /heartbeat. When the daemon PID file (same isolation-aware path as the token) records an HTTP port, the URL port must equal it; with no discoverable port any explicit port passes. The PID file is re-read per request. The client-only AUTOMOBILE_DAEMON_HTTP_TOKEN override takes precedence over file discovery. Keep the token and Authorization header out of logs and error reports.

Local HTTP clients obtain the token from the file; there is no unauthenticated fallback. The CLI, stdio proxy and daemon control commands use the Unix control socket and do not pass through HTTP ingress. Socket MCP forwarding uses the in-process transport rather than an HTTP request.

MCP transport and sessions

The daemon’s internal MCP endpoint (/auto-mobile/streamable) is stateless. Each request gets its own server and transport, and responses carry no mcp-session-id. There is no transport session to expire, so a daemon restart needs no replay on the client side. The one session key is the x-auto-mobile-mcp-session-id header (or the in-band __mcpSessionId argument). The socket server forwards its socket session id in that header, and the desktop app sends one id per app session. Tool-to-session bindings live in a daemon-scoped store rather than on any one server (#4678, #11820); see SDK v2 and stateless daemon layer.

A sessionUuid on a read is not a bearer capability (#13540). Reads follow the ownership rule control calls follow (#11344). A deviceReadOnly call can name a session another connected client owns (a derived base:label session counts as its base). The daemon then refuses it before admission with the non-retryable read_session_not_bound (ReadSessionNotBoundError, carrying the session and missingBinding: "session"). The exception is a calling connection that a broker binding granted that session, or that declared the session’s owner token.

The owning connection reads as before, and a session no connected client owns (its owner disconnected, such as a finished one-shot --cli call) stays readable by any connection, as it stays controllable. The check (readSessionBindingRefusal) runs in read-target resolution, so a refused read runs no readiness and records no activity. An id that names no live device session (an IDE observer session, #10968) still reads sessionlessly, and sessionless reads stay open (#10965). Calls with no connection identity (direct mode, and internal plan steps judged under their enclosing call) are not judged.