agent-device on the same Mac works with no operator step #952

Request: #950

Problem

agent-device is the primary way agents are meant to use Simlock, and it is the path with the most setup. Before the first agent-device open on the same Mac as the worker, an operator turns on capabilities.agent-device.enabled and http.enabled, restarts the daemon, and mints one agent token per agent. The agent exports the token and runs connect proxy against a URL the docs never state for localhost. A plain simlock lease needs none of this: the local socket identifies the user and the Claude Code or Codex session id identifies the agent.

Who it is for

A developer with one Mac running a standalone Simlock worker, whose coding agents (Claude Code, Codex, any CLI agent) drive simulators and emulators through the agent-device CLI on that same Mac.

Outcome

On a standalone worker with agent-device installed, an agent connects with one command that names a private file, then opens, uses and closes a device. Nobody runs a config set, restarts the daemon or mints a token first. Only the Mac user who runs the worker can read that file. Remote agents, joined workers and gateways work as today.

How it works for the user

flowchart TD
  S[simlock daemon start, standalone worker] --> H[HTTP on 127.0.0.1:4701, agent-device on]
  H --> P[writes ~/.simlock/agent-device-profile.json, readable by this user only]
  A[Agent, same user] -->|agent-device connect --remote-config profile --session id| C[connected]
  C -->|open / install / close, each with --session| D[device leased and driven]
  X[Other account or a browser page] -.cannot read the file.-> E[401 as today]
  N[agent-device not installed] --> Q[capability off, doctor quiet]

Before (the operator turned both settings on, restarted, and ran simlock token create --role agent):

$ export AGENT_DEVICE_DAEMON_AUTH_TOKEN=slk_…
$ agent-device connect proxy --daemon-base-url http://127.0.0.1:4701/v1/agent-device
$ agent-device open --platform ios

After (a fresh standalone worker, agent-device on PATH, no operator step):

$ agent-device connect --remote-config ~/.simlock/agent-device-profile.json --session "$CLAUDE_CODE_SESSION_ID"
$ agent-device open --platform ios --session "$CLAUDE_CODE_SESSION_ID"
$ agent-device install ./MyApp.app --session "$CLAUDE_CODE_SESSION_ID"
$ agent-device close --session "$CLAUDE_CODE_SESSION_ID"

All local agents share the profile's token. What keeps them apart is the agent-device session, so every command passes the agent's own --session. agent-device 0.21.28 runs a command with no --session flag in the session that connected last, which may be another agent's (dist/src/cli.js, allowActiveFallback; #931).

After the profile token is revoked and the worker restarts with a new one, agent-device answers Active remote connection config changed. Run agent-device connect --force to refresh it., and the agent reconnects with --force.

Examples

Defaults:

agent-device on a standalone worker that never set capabilities.agent-device.enabled:

What could go wrong

• Something else already listening on port 4701 stops the worker from starting after the upgrade, as an explicit http.enabled: true does today. The operator sets http.port or turns HTTP off.
• Local agents see each other's leased devices in agent-device devices. An agent that leaves --session off a command, or reuses another's name, drives the other agent's device, and nothing refuses it.
• Any program running as the same Mac user can read the profile and act as a local agent. The Unix socket already has the same boundary.
• Revoking the profile token cuts every local agent off until the next worker start.

Words used

• standalone worker: a worker daemon with no gateway.url, e.g. a developer's Mac. A joined worker has gateway.url set.
• profile: agent-device's remote-config file (--remote-config), here ~/.simlock/agent-device-profile.json. It holds the worker's agent-device URL and a token.
• profile token: the agent token the worker keeps in the profile, labelled agent-device on this Mac.
• session: agent-device's --session name. Each agent picks its own, e.g. its Claude Code session id.

Non-goals

• No change for remote agents, joined workers or gateways.
• No change to how Simlock checks credentials: the profile carries an ordinary agent token.
• No per-agent token or isolation: local agents share the profile token.
• No change to agent-device itself.
• No fallback when port 4701 is taken.
• The shipped agent instructions (Add simlock instructions: the rules an agent must follow, printable and served over MCP #147) are written there, not here.

Completion conditions

• A standalone worker with HTTP and agent-device on writes the profile at mode 0600, keeps the same bytes across restarts, and removes it when joined or turned off.
• With the profile, a real agent-device CLI with no token in its environment connects, opens an iOS simulator, installs an uploaded app and closes it (slow lane).
• A worker with no config.json and no gateway.url starts with HTTP on and agent-device on. A joined worker starts with both off.
• A standalone worker without agent-device on PATH starts, and simlock doctor lists no agent-device finding.
• The agent-device docs page gives the profile connect line, --session on every command, and the connect --force remedy, with no config set steps.

Open questions

none

Decisions

• ADR 0046 — A standalone worker serves agent-device by default and hands local agents a private profile (PR docs(adr): 0046 a standalone worker serves agent-device by default with a private profile #954): the defaults, the quiet not-found, the profile file, its token and its stability.

Shared values

Behaviours

Tasks

flowchart LR
  T1["#956 private agent-device profile"] --> T2["#957 on by default"]

• A standalone worker writes a private agent-device profile for local agents #956 A standalone worker writes a private agent-device profile for local agents — with HTTP and agent-device on, an agent on the Mac connects with the profile instead of a token. Risk: the file is missing, its token is refused, or it changes on every restart and forces connect --force.
• A standalone worker serves agent-device on localhost by default #957 A standalone worker serves agent-device on localhost by default — no config set or restart before the first use. Risk: a joined worker refuses to start, or doctor and the console complain on a Mac without agent-device.

Completion conditions:

• Profile written, stable and withdrawn: A standalone worker writes a private agent-device profile for local agents #956.
• Real CLI with the profile (slow lane): A standalone worker serves agent-device on localhost by default #957.
• Defaults on a standalone worker, off on a joined one: A standalone worker serves agent-device on localhost by default #957.
• No doctor finding without agent-device: A standalone worker serves agent-device on localhost by default #957.
• Docs: A standalone worker writes a private agent-device profile for local agents #956 adds the profile section; A standalone worker serves agent-device on localhost by default #957 drops the enable steps.

Open work in the same area:

• agent-device docs: parallel agents need their own --session #931 (bug, agent-device docs: --session per agent): the same page. The docs here state --session on every command. No Depends on; the bug stays agent-device's.
• Add simlock instructions: the rules an agent must follow, printable and served over MCP #147 (task:ready, simlock instructions): its body still teaches the token flow (AGENT_DEVICE_DAEMON_AUTH_TOKEN, connect proxy); a comment there points at the profile connect line. Its text is written there, not here. No Depends on.
• PR fix(daemon): exec children get a minimal environment; docs say what an agent token can do #891 edits gateway/access-control.mdx and remote-agents.mdx; A standalone worker serves agent-device on localhost by default #957 edits remote-agents.mdx:14-22. A text conflict only.
• PRs fix(daemon): status.get shows an agent only its own leases and queue entries #893 and feat(gateway): a join token is pinned to the first worker that uses it #894 edit gateway/access-control.mdx; feat(gateway): a join token is pinned to the first worker that uses it #894 also edits src/auth/index.ts (authenticateUplink), src/auth/AGENTS.md and src/daemon/main.ts (:913). A standalone worker writes a private agent-device profile for local agents #956 edits those files on other lines. Text conflicts only.
• Stream any running device to an operator by worker and device id #909's PR feat(stream): stream any running device by worker and device id #923 edits reference/configuration.mdx near :311; A standalone worker serves agent-device on localhost by default #957 edits :217 and :307. A text conflict only.
• Console: the worker's Events tab scrolls back through its history #911 (PR feat(history): the worker's Events tab scrolls back through its history #943) bumps the protocol. Neither task changes a contract shape, so there is no overlap.

Written by an agent.