Repository navigation
Description
Part of #1635.
Scope
With --url or SIMLOCK_URL and a token, every simlock command whose work is the daemon's runs against a standalone worker or a gateway from a machine with no daemon, with the token's role, and never starts a local daemon or falls back to an agent session. simlock simctl and simlock adb run on the lease's worker through device.exec, picking the lease this CLI's requester took. events --since replays from the farm, and baseline list/remove follow the farm's mode. Commands that act on this machine (daemon *, config set, setup) exit 2 in remote mode. A remote simlock lease without SIMLOCK_AGENT_ID or an agent session prints one notice. A held lease still ends on a dropped connection as today; the next task makes it reconnect.
A user would notice: a command that reaches this machine's daemon while --url is set, or the farm while --local is set; a local daemon started in remote mode; simctl acting on another agent's device; or any command behaving differently with no URL set.
Technical spec
Commit 1cd9315.
Rows
Behaviours: B6, B7
Interfaces: I6, I7, I11
Existing code: X9, X10, X11, X12, X13, X14, X25, X26, X27, X19 (reference/cli.mdx, using-devices/remote-agents.mdx, using-devices/ci.mdx)
Facts
| # | Fact | Source |
|---|---|---|
| F1 | Global flags (--token, --gateway, --local) are taken out of the whole argv before routing |
src/cli/index.ts:69-101 |
| F2 | The CLI's credential order is --token, SIMLOCK_ADMIN_TOKEN, the admin.token file, with an agent fallback and a notice |
src/cli/connect.ts:39-79 |
| F3 | Gateway passthrough picks its lease with resolveRemoteLeaseId and sends device.exec, with requesterId only for an admin |
src/cli/commands/passthrough.ts:49-80, src/cli/remote-lease.ts:44-50 |
| F4 | The lease the CLI requests carries the CLI's requester id | src/cli/commands/lease.ts:101, :213 |
| F5 | The CLI's requester id falls back to the process id when neither SIMLOCK_AGENT_ID nor a session variable is set |
src/cli/environment.ts:349, src/agent-identity/index.ts:30-37 |
| F6 | events without --follow connects with launch: false and reads history.db when no daemon answers |
src/cli/commands/events.ts:1, :29 |
Modules touched
src/cli/ (index.ts (global --url, the remote gate), tree.ts (CommandContext carries the URL and token), commands/rotate.ts (its default lease follows I11), environment.ts (remote connector, SIMLOCK_URL/SIMLOCK_TOKEN for all), connect.ts, types.ts, remote-lease.ts, commands/passthrough.ts, commands/events.ts, commands/baseline.ts, commands/tunnel.ts (URL from the context), commands/lease.ts (the notice), AGENTS.md), the new slow-lane test e2e/slow-remote-cli.test.ts, and the website pages reference/cli.mdx, using-devices/remote-agents.mdx, using-devices/ci.mdx. Searches: connectDaemonClient, connectAdmin, connectExistingAdmin, tunnelUrl, tunnelToken, daemon.mode === "gateway", daemonHome.role, GATEWAY_EXEMPT_PATHS, selectOnlyLease, resolveRemoteLeaseId.
Rules in play
- ADR 0081 §3: remote by URL; local-machine commands refused;
simctl/adbasdevice.exec. - ADR 0005 §19c: through a remote farm passthrough is
device.exec, the refusal list stays with the driver. src/cli/AGENTS.md: the router loads nothing (lazy-loading.test.ts): the remote gate and--urlparsing live in the router's static imports only as values it already may import; no decision logic beyond the connect choice.src/cli/AGENTS.mdOutput: errors as one JSON line; remote text throughescapeControl.- Documentation rule 9: the three website pages;
ci.mdxreplaces curl steps with commands and setsSIMLOCK_AGENT_ID.
Tests
Seam: runCli with a fake environment whose WebSocket connector reaches a fake session (models: src/cli/index-exit-codes-passthrough.test.ts, src/cli/index-admin-auto-launch.test.ts, src/cli/passthrough.test.ts).
- B6: remote mode selection: each row of both Examples tables;
--tokenbeatsSIMLOCK_TOKEN;SIMLOCK_ADMIN_TOKENnot sent; a rejected token (no fallback, no notice);tunnel --urlstill reaches its URL; nothing launched - B7: each command in remote mode:
status,lease,lease renew,release,list,catalog,doctor,token list(agent and operator);whoami;baseline listandremoveon a gateway; each of I7's commands;events --since 1h;simctl listappson a worker-mode farm;adb shell echo --stdin; each I11 case,rotateincluded;simlock leasewith and withoutSIMLOCK_AGENT_ID
Done when
pnpm test:changedpasses, with every Tests line above as a test, and every CLI test with no URL set passes unchanged.pnpm checkpasses,lazy-loading.test.tsincluded.- On a Mac with an iOS runtime:
scripts/slow-e2e.sh e2e/slow-remote-cli.test.tspasses. WithSIMLOCK_URLset to a worker's HTTP address (withHttpDaemon,e2e/helpers), an agent token andSIMLOCK_AGENT_ID, a CLI run from a data folder with no daemon doeslease --platform ios --detach,status,simctl listappsandrelease <id>, each exits 0, and no second daemon starts. - The website build passes:
pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs.
Out of scope
simlock mcptaking the URL and token, reconnecting a held lease, and MCP's remote mode (A held remote simlock lease and simlock mcp reconnect and keep their lease through a network drop #1642);simlock filesand the path hint (simlock files moves files to and from a remote lease's folder #1643).
Depends on
Written by an agent.
Activity