Skip to content

The CLI, simlock/client and simlock mcp reach a remote farm with a URL and a token #1635

Open
0 of 5 issues completed

Description

@V3RON

Request: #945

Problem

simlock talks only to the daemon on its own machine (using-devices/remote-agents.mdx: "Most simlock commands only talk to the daemon on their own machine"; simlock tunnel is the one exception). There is no URL-plus-token mode, so an agent on a laptop or a CI runner cannot simlock lease from a worker or a gateway. It writes one curl call per step against the HTTP API instead.

simlock/client and simlock/admin are local-socket only too (using-devices/programmatic-client.mdx: "Both only work on the same machine as the daemon"), so a remote Node.js program has no typed client. simlock mcp has the same gap, so an MCP agent on a laptop cannot use a shared farm.

Who it is for

  • A CLI agent (Claude Code, Codex, any shell agent) on a developer's laptop, using a shared worker or gateway.
  • A CI job on a Linux runner, which today writes curl calls for every step.
  • A Node.js tool on another machine that wants the typed client.
  • An operator who manages a farm from their own machine.

Outcome

  • With a farm URL and a token, every simlock command whose work is the daemon's runs against a standalone worker or a gateway, as it does on the daemon's own machine, with the token's role: an agent token gets agent commands, an operator token gets every command.
  • simlock/client and simlock/admin connect to a remote farm by URL and token, with the same calls, pushes and errors as on the local socket.
  • simlock mcp serves an agent from a remote farm.
  • simlock simctl and simlock adb run on the leased device's worker, and simlock files moves files to and from the lease's folder there.
  • A held simlock lease and simlock mcp ride out a network drop: they reconnect and keep renewing while the lease's time lasts.

How it works for the user

flowchart TD
  A[Agent: SIMLOCK_URL + SIMLOCK_TOKEN set] --> B{Command acts on this machine?}
  B -- yes: daemon start, setup, config set --> C[USAGE: runs only on the daemon's machine]
  B -- no --> D[Connects to URL /v1/session with the token]
  D -- no answer --> E[REMOTE_UNREACHABLE]
  D -- token refused --> F[UNAUTHENTICATED or FORBIDDEN]
  D -- other version --> G[PROTOCOL_VERSION_UNSUPPORTED]
  D -- connected --> H[Command runs with the token's role]
  H --> I[simlock lease holds and renews]
  I -- network drops --> J[Reconnects and renews until the deadline]
  J -- deadline passes --> K[LEASE_LOST, exit 14]
Loading

Before, from a CI runner or a laptop with no daemon:

$ export SIMLOCK_URL=https://farm.example.com SIMLOCK_TOKEN=slk_…
$ simlock lease --platform ios --detach
{"notice":"admin credential unavailable; connecting as agent (admin-only commands will fail with FORBIDDEN)"}
… starts a daemon on this machine, or fails with DAEMON_STARTUP_FAILED on Linux
$ curl -sS -X POST "$SIMLOCK_URL/v1/lease-requests" -H "Authorization: Bearer $SIMLOCK_TOKEN" -d '{"platform":"ios"}'

After:

$ export SIMLOCK_URL=https://farm.example.com SIMLOCK_TOKEN=slk_… SIMLOCK_AGENT_ID=ci-job-42
$ simlock lease --platform android --detach
{"leaseId":"w1.lse_3b9d…","device":{"platform":"android","model":"Pixel 9",…},"role":"agent",…}
$ simlock files put build/app-debug.apk
{"lease":"w1.lse_3b9d…","name":"app-debug.apk","size":48213901}
$ simlock adb install app-debug.apk
Success
$ simlock simctl install ./MyApp.app        # on an iOS lease
… simctl's own error …
{"notice":"./MyApp.app is a folder on this machine, and the command ran on the worker; a folder cannot be uploaded yet (#1636): install it with agent-device, or from a path on the worker"}
$ simlock release w1.lse_3b9d…
{"device":{"id":"dev_8c1f…","state":"reclaiming"},"released":true}
$ simlock daemon start
{"error":{"code":"USAGE","message":"`simlock daemon start` acts on this machine; it does not run with --url or SIMLOCK_URL. Run it on the daemon's machine, or unset SIMLOCK_URL."}}
$ SIMLOCK_TOKEN=wrong simlock status
{"error":{"code":"UNAUTHENTICATED","message":"https://farm.example.com refused the token: create one with `simlock token create` on the worker or gateway"}}

A held lease when the network drops:

$ simlock lease --platform ios
{"leaseId":"w1.lse_3b9d…",…}
{"notice":"lost the connection to https://farm.example.com; reconnecting until 2026-11-17T10:42:13Z to keep lease w1.lse_3b9d…"}
{"notice":"reconnected to https://farm.example.com; lease w1.lse_3b9d… renewed"}

Examples

The URL a command takes (--url, else SIMLOCK_URL). The rule is the one simlock tunnel has today (src/cli/commands/tunnel.ts:111-133).

--url / SIMLOCK_URL simlock tunnel today Any other command today After, every command
https://farm.example.com accepted ignored: local socket accepted
https://farm.example.com:8443 accepted ignored accepted
http://127.0.0.1:7801, http://localhost:7801, http://[::1]:7801 accepted ignored accepted
http://farm.example.com refused, exit 2 ignored refused, exit 2 (#1372 would change both)
https://farm.example.com/simlock refused: origin only ignored refused: origin only
https://farm.example.com/?x=1, …#a refused ignored refused
farm.example.com refused ignored refused
ws://farm.example.com refused ignored refused
empty SIMLOCK_URL= treated as unset ignored treated as unset: local mode

Which daemon a command reaches:

Flags and environment Today After
nothing set this machine's worker, or its gateway same
SIMLOCK_URL set this machine's daemon the remote farm
--url <u> tunnel only; any other command: unknown flag, exit 2 the remote farm
SIMLOCK_URL set and --local or --gateway this machine's daemon this machine's daemon: an explicit flag beats the environment
--url <u> and --local or --gateway exit 2 exit 2: --url cannot be used with --local or --gateway
SIMLOCK_URL set, no token this machine's daemon exit 2: No token: pass --token or set SIMLOCK_TOKEN

What could go wrong

  • An agent with SIMLOCK_URL left in its shell sends commands to the farm when it meant its own machine. Likely on a laptop that also runs a worker; every command's output names the farm's worker in the lease id, and --local forces the local daemon.
  • A network blip ends a CI step anyway, because the drop outlasted the lease's time. Unlikely with the default TTL; the notice lines say when it was lost.
  • A path in simlock adb install ./app.apk names the user's laptop, but the command runs on the worker and fails. Likely at first; the CLI prints a hint pointing at simlock files put.
  • An iOS agent expects simlock simctl install ./MyApp.app to work remotely. It cannot until Upload a folder or a build once for many leases, and put files into an app's container #1636, because a .app is a folder; the hint says so and names agent-device, which uploads apps today.
  • A network drop while simlock lease waits in the queue re-attaches to the same request. If the farm restarted meanwhile, the request queues again from the back (a gateway forgets it; a worker marks it failed and the CLI sends it once more). A farm out of reach for 5 minutes fails the step.
  • A CI job without SIMLOCK_AGENT_ID leases, and its next simlock adb finds no lease of its own. Likely at first; simlock lease prints a notice saying to set it, and --lease <id> always works.
  • An operator token on the network can stop work across the farm (nuke, cleanup, release --all). Same as the HTTP routes operator tokens reach today.

Words used

  • Remote mode: a command that has a farm URL and a token, and so talks to a worker or gateway over the network instead of this machine's daemon. Example: SIMLOCK_URL=https://farm.example.com simlock status.
  • Farm: a standalone worker or a gateway, reached by its HTTP address. A worker that has joined a gateway has HTTP off and is reached through its gateway.
  • Session path: the one WebSocket address on a farm, /v1/session, that carries the same messages the local socket carries.
  • Token: an agent or operator token made with simlock token create on that worker or gateway. Its role (agent or operator) is the session's role; an operator token gives the admin role.
  • Lease folder: the folder on the worker that holds a lease's files; simctl and adb run in it remotely, so a relative path names a file there. Example: simlock files put app-debug.apk, then simlock adb install app-debug.apk.
  • Requester id: who a lease is for, inside one token: SIMLOCK_AGENT_ID, else the agent session's id, else the process's. Two agents sharing one token are one owner but two requesters, and each one's commands pick only its own lease. Example: SIMLOCK_AGENT_ID=agent-a.
  • Re-attach: after a drop while simlock lease waits, sending the same request again with the same idempotency key, so the farm answers the request already waiting instead of starting a second one.

Non-goals

Completion conditions

  • With SIMLOCK_URL, SIMLOCK_TOKEN and SIMLOCK_AGENT_ID set to a standalone worker, simlock lease --platform ios --detach, simlock status, simlock simctl listapps, simlock release <id> all succeed from a machine with no daemon, and none of them starts a local daemon.
  • The same four commands succeed against a gateway, the lease landing on one of its workers.
  • With an agent token simlock token list fails with FORBIDDEN (exit 1); with an operator token it lists the farm's tokens.
  • simlock daemon start, daemon stop, daemon status, daemon logs, daemon install, daemon uninstall, config set and setup in remote mode exit 2 with the "acts on this machine" message and start nothing.
  • A wrong token fails with UNAUTHENTICATED (exit 1), an unreachable URL with REMOTE_UNREACHABLE (exit 1), and a farm of another protocol version with PROTOCOL_VERSION_UNSUPPORTED (exit 1).
  • simlock files put, list, get and rm move a file to and from the lease's folder, and simlock adb install <name> installs the uploaded .apk.
  • Two agents sharing one token, each with its own SIMLOCK_AGENT_ID and one lease, each run simlock adb shell echo hi without --lease, and each command lands on its own device.
  • simlock token revoke of a token closes its open sessions at once: a held remote simlock lease on it exits with UNAUTHENTICATED.
  • A remote simlock lease whose network drops while it waits in the queue is granted the same request once the network is back, and the farm shows one request, not two.
  • A Node program on another machine calls connectSimlock({ url, token }), leases, renews and releases, and receives lease-lost when an operator releases its lease.
  • simlock mcp with SIMLOCK_URL and SIMLOCK_TOKEN leases through lease_simulator, runs run_on_device, and releases on exit.
  • A held remote simlock lease whose network drops for less than its TTL prints the two notice lines and keeps the lease; one whose drop outlasts the TTL exits 14.
  • Every command run on the daemon's own machine with no URL set behaves exactly as on main.

Open questions

none

Decisions

  • ADR 0081 — A remote caller speaks the daemon protocol over one WebSocket path, with its token's identity (#1638): the session path, identity from the token, remote mode by URL, reconnect only in the lease-holding frontends.
  • ADR 0003 — One typed daemon contract behind every frontend: the dispatcher, roles, pushes, protocol ranges and errors are the same on the new path; §4, §5 and §10 are narrowed by ADR 0081.
  • ADR 0004 — TTL-first leases: a connection never kept a lease alive, so a reconnect only renews.
  • ADR 0005 — Gateway and worker modes: a joined worker has HTTP off; simctl/adb through a remote farm are device.exec, as through a gateway (§19c).
  • ADR 0067 — A lease has a file folder on its worker: simlock files calls its routes; exec runs in it.
  • Decided with the maintainer in the session of 2026-11-17: the transport is one WebSocket path on both a standalone worker and a gateway carrying the daemon protocol, not a client of the HTTP routes.
  • Decided with the maintainer in the session of 2026-11-17: operator commands work remotely with an operator token; only commands that act on this machine are refused.
  • Decided with the maintainer in the session of 2026-11-17: remote simctl/adb paths are the worker's; a new simlock files put/get/list/rm uploads, and a failed command that named a local file prints a hint.
  • Decided with the maintainer in the session of 2026-11-17: a held simlock lease and simlock mcp reconnect after a drop and keep renewing until the lease's deadline.
  • Decided with the maintainer in the session of 2026-11-17 (after the design check): uploading a folder (an iOS .app) and unpacking it moves to Upload a folder or a build once for many leases, and put files into an app's container #1636; this feature ships single-file uploads, so a remote .apk install works and a remote .app install goes through agent-device until then.
  • Decided with the maintainer in the session of 2026-11-17 (after the design check): in remote mode simctl, adb and files without --lease pick only a lease whose requester is this CLI's requester id, whatever the role, so two agents sharing one token never act on each other's device.
  • Decided with the maintainer in the session of 2026-11-17 (after the design check): a drop while simlock lease waits for its grant reconnects and re-attaches to the same request by its idempotency key, until the request's own timeout.
  • Decided with the maintainer in the session of 2026-11-17 (after the design check): token.revoke closes every open session of that token at once, on a worker and on a gateway.
  • Decided with the maintainer in the session of 2026-11-17 (at the recheck): the default lease is filtered by requester id always, with no fallback to the token's only lease; a CI job or a plain shell sets SIMLOCK_AGENT_ID, or passes --lease. Without one of them each process is its own requester (its pid, src/agent-identity/index.ts:30-37).
  • Decided with the maintainer in the session of 2026-11-17 (at the recheck): when a re-attach is answered with a worker's restart failure, the CLI sends the request once more with a new key and a notice; a second such answer ends the command.
  • Decided with the maintainer in the session of 2026-11-17 (at the recheck): a re-attach before the grant gives up after 5 minutes without reaching the farm (REMOTE_UNREACHABLE, exit 1), or at the request's --timeout when that comes first; a connected wait in the queue stays unlimited as today.
  • Decided in the session: the CLI knows a worker's restart failure by the re-attach's INTERNAL answer, not by its words: a replay carries only the stored code and message (src/leasing/lease-request-book.ts:402-409), the restart failure is stored as INTERNAL (src/leasing/lease-startup.ts:37-40), and a re-send with a new key is safe for any stored INTERNAL failure because it starts one new request, once.
  • Decided in the session: in remote mode a simlock lease whose requester is the pid fallback prints one notice saying later commands need SIMLOCK_AGENT_ID or --lease, because that is the one setting a CI job must add.
  • Decided in the session: a remote client counts 45 s with no ping from the farm as a lost connection, because a drop with no close frame (sleep, Wi-Fi switch) is otherwise never noticed; it is simlock tunnel's bound (SILENCE_TIMEOUT_MS), three of the farm's 15 s pings.
  • Decided in the session: after a reconnect, a renew answer that a restart gives (WORKER_UNREACHABLE, DAEMON_STOPPING, a lost connection, no answer) is retried until the deadline; UNKNOWN_LEASE or FORBIDDEN is the lease lost (exit 14); a refused reconnect (UNAUTHENTICATED, PROTOCOL_VERSION_UNSUPPORTED) stops at once with that code and today's "still yours" line, because no later try can succeed. MCP already never reconnects after a refused handshake (src/mcp/AGENTS.md).
  • Decided in the session: a remote simlock lease sends a random idempotency key unless --requires is given (the two cannot be combined, src/contract/operations-lease-request.ts:156); with --requires a drop while waiting reconnects once and cancels the request, as today's abort does.
  • Decided in the session: a session's identity.get reports via and name as HTTP does for the same identity (token or proxy, the token's name), because whoami should name the token the session runs as.
  • Decided in the session: simlock files bounds a transfer by silence, not total time: 60 s with no byte moving either way ends it with REMOTE_UNREACHABLE, because a 2 GiB upload has no sensible total limit and the farm already cuts an upload only after 330 s of silence.
  • Decided in the session: the flags and variables are --url/SIMLOCK_URL and --token/SIMLOCK_TOKEN, the flag winning over the variable, because simlock tunnel already reads exactly these and the reference already says --token is the bearer token tunnel sends.
  • Decided in the session: the URL rule is tunnel's, moved to one shared place, because two rules for one variable would disagree; simlock tunnel refuses plain http to a Tailscale gateway #1372 then changes both at once. The shared function throws its own error with the message; the CLI turns it into a usage error (exit 2) and the typed clients into a TypeError.
  • Decided in the session: an explicit --local or --gateway beats SIMLOCK_URL, and --url with either is a usage error, because a flag is what the user typed for this command and the variable may be left over in a shell.
  • Decided in the session: remote mode needs a token and never falls back to an agent session or launches a daemon, because a token decides the role and there is no local daemon to fall back to.
  • Decided in the session: on the session path a hello principal is not believed and a hello credential is refused with BAD_REQUEST, because one connection must carry one identity, the token's.
  • Decided in the session: the CLI and MCP send their requester id (SIMLOCK_AGENT_ID, the agent session's id, or the process's) as requesterId on lease.request in remote mode, because the principal is now the token's and the one-lease-per-requester rule keys on the requester, which an agent may already set (src/daemon/dispatcher-leases.ts:24).
  • Decided in the session: simlock files works in remote mode only, because on the daemon's own machine the lease folder is a local folder and there is no token to send.
  • Decided in the session: simlock/client keeps exposing agent calls only, even when an operator token makes its session admin, because the package split is by import path (ADR 0003 §10); simlock/admin is the one with every call.
  • Decided in the session: the session path has its own WebSocket server, apart from the lease sockets' 1 MiB one (src/ports/upgrade-router.ts:39), so its 32 MiB bound holds. A session message from a caller is bounded at 32 MiB, because the largest request is device.exec with up to 8 Mi characters of stdin (EXEC_STDIN_MAX_LENGTH) and JSON may escape each into several bytes; a reply is bounded only by the client's 128 Mi character line cap, as on the socket.
  • Decided in the session: a held lease's reconnect waits 1 s, then doubles to at most 15 s between tries, never past the deadline, because a gateway restart takes seconds and a renew is due only every third of the TTL.

Behaviours

Id Behaviour (invoker, action, what it sees) Seam Cases Task
B1 A remote caller opens the session path (I1) on a standalone worker and on a gateway: an accepted upgrade gets a session whose hello reply names the token's role and principal, and whose identity.get names the token (I2); a refused one gets the HTTP answer and no socket the HTTP listener with its upgrade router (createUpgradeRouter with the app's session handler), a ws test client, fake drivers agent token (role agent, via: token, the token's name); operator token (role admin); no Authorization (401); unknown or revoked token (401); worker join token (403); proxy-signed identity with Sec-Fetch-Site: same-origin (accepted, admin, via: proxy); the same cross-site (403); /v1/session/x (404); the worker and the gateway each pass the same table #1639
B2 A session's hello is answered as on the socket but for identity: a principal it names is not used, a credential is refused and the socket closed, a version outside the range leaves it open with PROTOCOL_VERSION_UNSUPPORTED hello over the session path, as B1 principal: "someone-else" (reply principal is the token's); credential set (BAD_REQUEST, I2's message, closed); range below the daemon's (PROTOCOL_VERSION_UNSUPPORTED, then daemon.update with query still answers); a request before hello (HANDSHAKE_REQUIRED, closed, as on the socket) #1639
B3 Calls and pushes over a session behave as over the socket, for the token's principal session path, fake drivers lease.request streams its progress and grants, owner the token's principal; lease.request with requesterId (the lease's requester is it); the same lease.request with the same idempotency key on a second session while the first waits (attaches, one request); a second session of the same token releases the lease (the first gets lease-lost); TTL expiry (lease-lost); an agent's lease.list holds only the token's leases; events.subscribe with an operator token streams events; closing the session mid-request leaves the request and the lease going on #1639
B4 A session's limits hold: a caller's message over 32 MiB or a binary message closes the socket without running it, a peer that stops answering pings is closed, a proxy-signed session ends at the identity's expiry session path with the fake clock a 33 MiB message (closed with 1009, no request ran); a 9 MiB device.exec with 8 Mi stdin (runs); a binary message (closed with 1003, nothing run); no pong for two ping intervals (closed); a proxy identity whose expiresAt passes (closed with 4001) #1639
B12 An operator revokes a token: every open session of it on that daemon closes at once with 4003 token revoked; other tokens' sessions stay; its leases run on to their TTL token.revoke through the dispatcher, sessions open on the session path, on a worker and on a gateway one session of the token (closed 4003); two sessions (both closed); a session of another token (open); the revoked token's lease (still listed, expires at its deadline); a reconnect with it (401) #1639
B5 A Node program calls connectSimlock({ url, token }) or connectSimlockAdmin({ url, token }) (I3): it gets a client that works as a local one, or the remote error (I4) src/client/index.ts and src/admin/index.ts against a test server on the session path, with the fake clock worker URL; gateway URL; a refused URL shape (TypeError with I5's message, nothing sent); url with connection, endpoint, ipc or credential (TypeError); a token over MAX_TOKEN_CHARS (TypeError); nothing listening (REMOTE_UNREACHABLE); no answer in 10 s (REMOTE_UNREACHABLE); 401 (UNAUTHENTICATED); 403 (FORBIDDEN); 404 at the path (REMOTE_UNREACHABLE, "no Simlock session" message); 502 from a proxy (REMOTE_UNREACHABLE, status message); other protocol version (degraded client, PROTOCOL_VERSION_UNSUPPORTED as today); lease-lost push arrives; a reply of 60 MiB arrives whole; the connection drops (DAEMON_CONNECTION_LOST, no reconnect); no ping for 45 s (DAEMON_CONNECTION_LOST); close 4003 (UNAUTHENTICATED, "the token was revoked") #1640
B6 A user runs a command with --url or SIMLOCK_URL (I6): it connects to the farm with the token and no admin-file or launch step, or stops with a usage error runCli with a fake environment whose WebSocket connector reaches a fake session each row of both Examples tables; --token beats SIMLOCK_TOKEN; SIMLOCK_ADMIN_TOKEN is not sent remotely; a rejected token (UNAUTHENTICATED, no agent fallback, no notice line); simlock tunnel --url <u> still reaches <u> with --url now a global flag; no daemon is launched in any case #1641
B7 A user runs each command in remote mode: a daemon command works with the token's role; a command that acts on this machine exits 2 with I7; events --since replays from the farm; simctl and adb run as device.exec on the lease, also on a standalone worker, picking the default lease by requester (I11) runCli with the fake session, per command status, lease, lease renew, release, list, catalog, doctor, token list (agent: FORBIDDEN; operator: answers); whoami (prints Via: token and the token's name); baseline list and baseline remove against a gateway (gateway output and refusals, read from status.get's mode, not this machine's folder); each of I7's commands (exit 2, nothing sent); events --since 1h (calls events.replay, never opens history.db); simctl listapps against a fake worker whose status.get says worker (sends device.exec, not driver.passthrough); adb shell echo with --stdin; each case of I11: one lease of this requester (used), none (usage error), two (usage error), another requester's lease on the same token only (usage error, never used), --lease naming it (used); simlock lease with no SIMLOCK_AGENT_ID and no session variable (the notice), with SIMLOCK_AGENT_ID (no notice) #1641
B8 A user runs simlock files put, list, get or rm (I8) in remote mode: it calls the lease-files routes with the token and prints I8's output, or the route's error runCli with a fake streaming HTTP port answering the lease-files routes, and the fake clock put of a file (201, prints I8); put --name x; put of a missing local file (exit 2, nothing sent); put of a folder (exit 2, I8's folder message); get to stdout and to -o <file>; list; rm; each case of I11; 413 FILE_TOO_LARGE; 413 LEASE_FILES_FULL; 409 FILE_BUSY; 422 INSUFFICIENT_DISK_SPACE; 408 UPLOAD_STALLED; 404 UNKNOWN_LEASE; 404 UNKNOWN_FILE on get and rm; 401 (UNAUTHENTICATED); farm unreachable (REMOTE_UNREACHABLE); 60 s with no byte moving (REMOTE_UNREACHABLE); a 2 GiB upload taking 20 minutes with bytes moving (completes); local mode (exit 2, I8's message) #1643
B9 A remote simctl or adb that exits non-zero and named a path that exists on this machine prints one hint (I9) to stderr after its output; its exit code is the tool's runCli remote passthrough with a fake device.exec and a fake filesystem adb install ./app.apk, the local file exists, exit 1 (file hint); simctl install ./MyApp.app, a local folder, exit 1 (folder hint); same, exit 0 (no hint); install app.apk, no such local path, exit 1 (no hint); two local paths (one hint, the first); local mode (no hint) #1643
B10 A held remote simlock lease whose connection drops reconnects (I10): before the grant it re-attaches to its request, after the grant it renews until the lease's deadline, then holds on or ends simlock lease (held and --detach) with a fake session that drops or goes silent, and the fake clock drop after the grant and back before the deadline (two notice lines, renewed, holds on); 45 s of silence with no close (treated as a drop); back but UNKNOWN_LEASE (exit 14); back but WORKER_UNREACHABLE for 50 s, then renewed (holds on); never back before the deadline (exit 14 at the deadline, no try after it); a reconnect answered 401 (exit 1 UNAUTHENTICATED, "still yours" line, no more tries); a reconnect answered PROTOCOL_VERSION_UNSUPPORTED (stops the same way); tries at 1, 2, 4, 8, 15, 15 s; drop while queued and back (same idempotency key re-sent, granted, one request on the farm); drop while queued past the request's timeout (QUEUE_TIMEOUT as today); drop while queued and a worker restart (INTERNAL "send it again with a new key" answered; re-sent once with a new key, notice, granted); a second restart (exit 1); drop while queued with no --timeout and the farm gone for 5 minutes (REMOTE_UNREACHABLE, exit 1, no try after); drop while queued with --requires (one reconnect, lease.cancel, exit as today); Ctrl-C while disconnected (one connect and release within RELEASE_TIMEOUT_MS, else exit 0 with the "still yours" line); a close 4003 (exit 1 UNAUTHENTICATED); a local held lease whose socket drops (today's behaviour, no reconnect) #1642
B11 An agent runs simlock mcp with --url/SIMLOCK_URL and a token (I6): tool calls and renewals use the farm, nothing is launched, a drop is ridden out as in B10, and the end releases simlock mcp over stdio with a fake session, started through runCli so the global flags reach it lease_simulator (sent with requesterId and an idempotency key, granted); run_on_device; lease_status; the renew after a drop reconnects and renews; 45 s of silence (treated as a drop); a drop past the deadline (lease-lost logging message); a refused reconnect (logging message, no more tries); stdin EOF releases; --url and no token (the server exits 2 at start with I6's message) #1642

Stored state

none

The feature stores nothing. A session's identity lives in its connection; leases, tokens and lease files are today's records.

Interfaces

Id What Shape and bounds Errors and limits Where Task Used by
I1 Session path GET /v1/session, WebSocket upgrade, on a standalone worker's and a gateway's HTTP listener Authorization: Bearer <token>, or a proxy-signed identity, as every route (requireAuth); its own WebSocketServer with maxPayload 32 MiB, apart from the lease sockets' 1 MiB one; one text message is one protocol line, without its \n; a write holding several lines is sent as one message per line; session joins CORE_ROUTE_SEGMENTS, which bumps the protocol by one 401 UNAUTHENTICATED, 403 FORBIDDEN (join token, cross-site ambient), as HTTP JSON bodies, no socket; a caller message over 32 MiB: close 1009, not run; a binary message: close 1003, not run; ping every 15 s (CLIENT_PING_INTERVAL_MS), no pong by the next ping: closed; an identity's expiresAt: close 4001 identity expired; token.revoke: close 4003 token revoked for each session of that token, at once; closing runs today's connection close (requests and leases go on) src/http (route and session adapter), src/ports/upgrade-router.ts, src/daemon (accepting the connection, the revoke hook), wired in worker-composition.ts and main.ts #1639 #1640
I2 Session identity the daemon accepts the connection with the role from toRole (src/http/dispatcher-session.ts), and the principal, name and via (token or proxy) from the identity, as buildHttpSession does, before hello; hello keeps its range, capabilities and reply hello with credential: BAD_REQUEST "A session's identity is its token: send no credential in hello", then closed; hello.principal is ignored, the reply's principal is the token's src/daemon/server.ts, server-hello.ts, server-requests.ts (identity.get) #1639 #1640
I3 connectSimlock({ url, token, signal? }), connectSimlockAdmin({ url, token, signal? }) url: string, I5's rule; token: 1 to MAX_TOKEN_CHARS characters, as tunnel; url excludes connection, endpoint, ipc, credential and principal; connects over a WebSocket connector (lazy ws) that sends text frames and accepts messages up to MAX_WIRE_LINE_CHARS; connect waits at most 10 s (CONNECT_TIMEOUT_MS), counted from the call; after connecting, 45 s with no ping from the farm closes the connection as lost (SILENCE_TIMEOUT_MS, today tunnel's) a bad url, a bad token or a mixed option: TypeError with the rule's words, nothing sent; I4 for the rest; a silent or dropped connection: every call rejects DAEMON_CONNECTION_LOST and onConnectionLost fires, as on the socket; close 4003: calls reject UNAUTHENTICATED "the token was revoked"; never reconnects src/simlock-client, src/client/index.ts, src/admin/index.ts, src/ports/websocket-client.ts #1640 #1641, #1642, #1643
I4 Remote connect errors REMOTE_UNREACHABLE: kind transport, exit 1, HTTP 503, details { url }; message No answer from <origin>: <reason> (DNS, refused, TLS, timeout, silence), <origin> answers no Simlock session at /v1/session: is it a Simlock worker or gateway of this version or later? (404), or <origin> answered <status> to the session upgrade (any other status); UNAUTHENTICATED: kind protocol, exit 1, HTTP 401, details none, message <origin> refused the token: create one with \simlock token create` on the worker or gateway; 403 maps to FORBIDDENwith the farm's message; both codes joinErrorDetailsMapandERROR_TABLE`, which bumps the protocol by one — src/contract/errors.ts, src/simlock-client #1640 #1641, #1642, #1643
I5 Farm URL rule, one function used by tunnel, the CLI, MCP and the typed clients https://<host>[:port], or http:// for 127.0.0.1, [::1] or localhost; origin only: no path but /, no query, no fragment; at most MAX_URL_CHARS throws FarmUrlError with today's tunnel messages (src/cli/commands/tunnel.ts:113-139), "worker URL" and "the worker's origin" read as "farm URL" and "the farm's origin"; the CLI turns it into a usage error (exit 2), the typed clients into a TypeError moved from tunnel.ts into src/simlock-client #1640 #1641, #1642, #1643
I6 Remote mode in the CLI and MCP URL: --url <u>, else SIMLOCK_URL (empty is unset); token: --token, else SIMLOCK_TOKEN; an explicit --local/--gateway turns remote mode off; --url is a global flag like --token, handed to tunnel and mcp through the command context --url with --local or --gateway: exit 2 --url cannot be used with --local or --gateway; URL and no token: exit 2 No token: pass --token or set SIMLOCK_TOKEN; a bad URL: exit 2, I5's message src/cli/index.ts, src/cli/environment.ts, src/cli/connect.ts #1641 #1642, #1643
I7 Commands refused in remote mode daemon start, daemon stop, daemon status, daemon logs, daemon install, daemon uninstall, config set, setup exit 2 USAGE: `simlock <command>` acts on this machine; it does not run with --url or SIMLOCK_URL. Run it on the daemon's machine, or unset SIMLOCK_URL. src/cli/index.ts #1641 —
I8 simlock files put <file> [--name <n>], files get <name> [-o <file>], files list, files rm <name>, each with [--lease <id>] calls PUT, GET, GET (list) and DELETE on /v1/leases/{id}/files[/{name}] with the bearer token, over a streaming HTTP port of the CLI (no body cap, no total time limit; connect 10 s; 60 s with no byte moving either way ends it); <n> follows the file name rule (LEASE_FILE_NAME_PATTERN, 1 to 128 characters), default the file's base name; put streams the file and prints {"lease","name","size"}; get writes raw bytes to stdout or -o; list prints the route's JSON; rm prints nothing; the lease defaults by I11 route errors keep their codes and exit codes from ERROR_TABLE (FILE_TOO_LARGE, LEASE_FILES_FULL, FILE_BUSY, INSUFFICIENT_DISK_SPACE, UPLOAD_STALLED, UNKNOWN_LEASE, UNKNOWN_FILE); 401 UNAUTHENTICATED; no answer or 60 s of silence: REMOTE_UNREACHABLE; a missing local file: exit 2 No file <file>; a folder: exit 2 <file> is a folder; a folder cannot be uploaded yet (#1636); local mode: exit 2 simlock files needs --url or SIMLOCK_URL: on the daemon's machine the lease's folder is a local folder src/cli/commands/files.ts, src/ports (a streaming HTTP adapter beside the GET-only http-json.ts) #1643 —
I9 Remote passthrough hint one stderr line after the tool's output, for the first argument that names an existing local path: a file, {"notice":"<path> is on this machine, but the command ran on the worker; upload it with \simlock files put ` and name it by its file name"}; a folder, {"notice":" is a folder on this machine, and the command ran on the worker; a folder cannot be uploaded yet (#1636): install it with agent-device, or from a path on the worker"}` only on a non-zero exit in remote mode src/cli/commands/passthrough.ts #1643 —
I10 Held-lease reconnect, CLI and MCP on a lost remote connection (I3): notice {"notice":"lost the connection to <origin>; reconnecting until <deadline ISO> to keep lease <id>"}, or before the grant {"notice":"lost the connection to <origin>; reconnecting to the waiting request"}; tries after 1, 2, 4, 8 s, then every 15 s, none after the lease's deadline (before the grant: the request's timeoutMs); after a grant, each connect sends lease.renew; before it, lease.request again with the same idempotency key, and when that re-attach is answered INTERNAL (a worker's restart failure) once more with a new key and the notice {"notice":"<origin> restarted and dropped the waiting request; asking again"}; before the grant, tries stop after 5 minutes without reaching the farm, or at timeoutMs when sooner; success: notice {"notice":"reconnected to <origin>; lease <id> renewed"}; a remote simlock lease and MCP's lease_simulator send a random idempotency key unless --requires is set; MCP sends the notices as logging messages renew UNKNOWN_LEASE or FORBIDDEN, or the deadline passing: today's LEASE_LOST, exit 14 (MCP: today's lease-lost logging message); renew WORKER_UNREACHABLE, DAEMON_STOPPING, a lost connection or no answer: tried again; a reconnect refused UNAUTHENTICATED or PROTOCOL_VERSION_UNSUPPORTED: stops at once with that code and today's "still yours" line; with --requires, a drop before the grant reconnects once and sends lease.cancel; 5 minutes unreachable before the grant: REMOTE_UNREACHABLE, exit 1; a second INTERNAL re-attach answer: that failure, exit 1; the typed client still never reconnects src/cli/commands/lease.ts, src/mcp/session.ts, src/lease-policy #1642 —
I11 Default lease in remote mode, for simctl, adb and files the token's leases (lease.list) whose requesterId is this CLI's requester id, for an agent and an operator token alike; --lease <id> names any lease the token may act on none: usage error No lease is held by <requester>: run \simlock lease` first, or set SIMLOCK_AGENT_ID to the id that holds it; several: usage error holds more than one lease (); pass --lease to name the device you mean(today's words,src/cli/remote-lease.ts:32-41); simlock leasein remote mode with the pid fallback requester prints{"notice":"no SIMLOCK_AGENT_ID or agent session: this lease's requester is , this process; set SIMLOCK_AGENT_ID, or pass --lease , for later commands to find it"}` src/cli/remote-lease.ts, src/cli/commands/lease.ts #1641 #1643

Existing code

Commit 1cd9315.

Searches: resolveDaemonSocketPath in src/cli and src/mcp (4 hits), connectSimlock/connectSimlockAdmin callers (11), SIMLOCK_URL/SIMLOCK_TOKEN (6), forcedRole (5), UPLINK_PATH/LEASE_SOCKET_PATH (7), daemon.mode === "gateway" (2), onConnectionLost in src/cli and src/mcp (5), GATEWAY_EXEMPT_PATHS (2), principal ?? in src/daemon (3), toRole (2), CORE_ROUTE_SEGMENTS (4), the website pages naming "same machine" or "own machine" (5).

Id Code (path:line) Today With this feature Handled by
X1 src/daemon/server-hello.ts:90 the principal is hello.principal or the default requester id; the role comes from hello.credential unless the connection has a forced role a session connection arrives with role and principal set by I2; hello keeps them and refuses a credential B2, #1639
X2 src/ports/upgrade-router.ts:50 routes /v1/uplink (gateway only) and /v1/leases/<id>/<module>; anything else 404 also routes /v1/session to the session handler on both a worker and a gateway B1, #1639
X3 src/daemon/worker-composition.ts:714, src/daemon/main.ts:682 the worker attaches the router with lease sockets; the gateway with lease sockets and uplinks both pass the session handler too B1, #1639
X4 src/http/server.ts:47 comment: "Undefined on a worker, which upgrades nothing" (stale: X3) comment says what each role upgrades #1639
X5 src/http/dispatcher-session.ts:25, src/http/auth.ts:34 HTTP maps operator → admin, agent → agent; an ambient identity's upgrade needs Sec-Fetch-Site: same-origin the session path takes its identity through the same two B1, #1639
X6 src/daemon/server.ts:472, src/daemon/server.ts:658 the uplink is accepted as admin; a closed connection ends its pushes, its requests go on a session is accepted with the token's identity (I2); its close is the same close B3, #1639
X7 src/ports/uplink-websocket.ts:415, src/simlock-client/wire.ts:24, src/contract/operations-leases.ts:96 uplink messages are capped at 8 MiB; a client line at 128 Mi characters; exec stdin at 8 Mi characters the session caps a caller's message at 32 MiB and the client's incoming at the line cap (I1, I3) B4, #1639, #1640
X8 src/client/index.ts:62, src/admin/index.ts:116-122 both build a NodeIpcTransport unless a connection is passed url and token build the WebSocket connector instead (I3) B5, #1640
X9 src/cli/commands/tunnel.ts:115, src/cli/environment.ts:480 the URL rule and SIMLOCK_URL/SIMLOCK_TOKEN are tunnel's alone the rule is shared (I5); the variables select remote mode for every command (I6) B6, #1640, #1641
X10 src/cli/environment.ts:383, src/cli/connect.ts:39 every daemon command connects to the local socket, may launch a daemon, and falls back to agent on a rejected or missing admin credential with a notice in remote mode it connects with I3, launches nothing and never falls back B6, #1641
X11 src/cli/index.ts:184 GATEWAY_EXEMPT_PATHS lists the commands that run without a gateway I7 is its own list, checked before any connect B7, #1641
X12 src/cli/commands/passthrough.ts:26 device.exec only when status.get says gateway; otherwise the command is resolved and spawned here in remote mode always device.exec, on a worker too B7, #1641
X13 src/cli/commands/events.ts:29 --since without a running daemon reads history.db in remote mode it always calls events.replay on the farm B7, #1641
X14 src/cli/remote-lease.ts:6 tunnel picks the token's only lease, refuses none or several unchanged for tunnel; remote passthrough and simlock files use I11 instead B7, B8, #1641, #1643
X15 src/http/lease-declarations.ts:393, src/http/lease-declarations.ts:439 the lease-files routes, reached by curl simlock files calls them (I8) B8, #1643
X16 src/cli/commands/lease.ts:159, src/lease-policy/index.ts:38 a lost connection prints "still yours" and ends the held command; renewal at a third of the TTL in remote mode the command reconnects and renews (I10); local unchanged B10, #1642
X17 src/mcp/main.ts:202, src/mcp/main.ts:221, src/mcp/session.ts:50 tool calls may launch a local daemon; renewals connect only to a running one; a dead client is replaced on next use in remote mode both connect with I3, nothing launches; the renew rides out a drop (I10) B11, #1642
X18 src/contract/protocol.ts:82 the core route segments a module name may not start with adds session I1, #1639
X19 website using-devices/programmatic-client.mdx, using-devices/remote-agents.mdx, using-devices/ci.mdx, reference/cli.mdx, reference/errors.mdx, getting-started/connect-your-agent.mdx, gateway/access-control.mdx say the CLI and the typed clients work only on the daemon's machine; CI uses curl each describes remote mode, I4's codes and simlock files, in the task that ships it #1639–#1643
X20 src/ports/upgrade-router.ts:39, src/ports/upgrade-router.ts:44 one WebSocketServer with a 1 MiB maxPayload serves every lease socket the session path gets its own server with 32 MiB (I1); lease sockets keep 1 MiB B4, #1639
X21 src/ports/websocket-client.ts:62-64, src/ports/websocket-client.ts:89-96 the client port sends binary frames only and takes ws's default 100 MiB maxPayload it sends text frames for a session and accepts up to MAX_WIRE_LINE_CHARS (I3); tunnel keeps binary B5, #1640
X22 src/cli/commands/tunnel.ts:317 tunnel alone ends a socket after 45 s without a ping the typed client's remote connector uses the same bound (I3) B5, B10, #1640
X23 src/daemon/server-requests.ts:366, src/daemon/dispatch.ts:156 identity.get says via: socket or uplink; name falls back to the principal a session says via and name from its identity (I2) B1, #1639
X24 src/gateway/dispatcher.ts:433, src/daemon/dispatcher-admin.ts:66 a gateway's token.revoke closes the revoked token's uplinks; a worker's only revokes it also closes the token's sessions, here and on a worker (I1) B12, #1639
X25 src/cli/commands/baseline.ts:45, src/cli/commands/baseline.ts:74 baseline list and remove take the gateway branch from this machine's daemon folder in remote mode they take it from status.get's mode B7, #1641
X26 src/cli/index.ts:68-99, src/cli/commands/tunnel.ts:689, src/cli/commands/mcp.ts:23 global flags are taken out of argv before routing; tunnel reads --url from its own arguments; mcp hands the MCP server only the daemon flag --url is global and reaches tunnel and mcp through the command context (I6) B6, B11, #1641, #1642
X27 src/cli/remote-lease.ts:27-30, src/auth/strategies/token/index.ts:31 a token's principal is its id; the default lease is filtered by requester only for an admin in remote mode the default lease is filtered by requester for every role (I11) B7, #1641
X28 src/leasing/lease-request-book.ts:166-167 a repeat under the same requester and idempotency key returns the stored result or attaches to the open wait, on a worker and a gateway a remote simlock lease re-attaches this way after a drop (I10) B3, B10, #1642
X29 src/ports/http-json.ts:1, src/ports/http-json.ts:10 the CLI's HTTP port: GET only, 10 s per call, 1 MiB body simlock files uses a new streaming adapter beside it (I8) B8, #1643
X30 docs/internal/adr/0067-a-lease-has-a-file-folder-on-its-worker-that-http-callers-fill-and-read.md:148 unpacking an uploaded archive into folders (an iOS .app) is out of ADR 0067 stays out here: #1636 B9
X31 src/leasing/lease-startup.ts:37-40, src/leasing/lease-request-book.ts:402-409 a worker start stores every open request failed INTERNAL "send it again with a new key"; a repeat of its key replays that failure a remote simlock lease re-attaching after a worker restart sends once more with a new key (I10) B10, #1642

Tasks

flowchart LR
  A[#1639 session path] --> B[#1640 remote typed client]
  B --> C[#1641 CLI remote mode]
  C --> D[#1642 reconnect, MCP remote]
  C --> E[#1643 simlock files]
Loading

Completion conditions and the task that delivers each:

Open work in the same area:

Written by an agent.

Activity

  1. added
    feature:specSpec in progress, business and technical together.
    on Nov 17, 2026
  2. V3RON commented on Nov 17, 2026

    @V3RON
    ContributorAuthor

    Design posted: business sections, Decisions (ADR 0081 in #1638 and the session's choices), Behaviours B1–B11, Interfaces I1–I10, Existing code X1–X19; no stored state. Tasks T1–T5 are named in the rows and written after the check and approval.

    Written by an agent.

  3. V3RON commented on Nov 17, 2026

    @V3RON
    ContributorAuthor

    Spec updated: design approved; ADR 0081 accepted (not yet implemented) on #1638. Tasks #1639–#1643 written as sub-issues; Task cells and Used by now name them; Tasks section added. Interfaces I8 names LEASE_FILE_NAME_PATTERN.

    Written by an agent.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature:specSpec in progress, business and technical together.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions