Named baselines: a lease starts from a device the operator prepared #327

Request: #1049

Problem

Every lease starts from a factory-fresh device, and every agent does the same setup on it before the real work starts: install the app under test, trust a certificate, sign into a test account, set a locale, grant permissions, seed data. That takes minutes per lease, is repeated by every agent on every lease, and is done slightly differently each time. Reclaim wipes the device back to factory, so the work is thrown away on release. Teams report reinstalling Firefox's split APKs on every Android lease, and being stuck with the system image's old Chrome (113 on an API 34 image), which could not load their game's 3D models (#327, leonardoxr).

Operators have no way to prepare a device once and hand copies of it out.

The factory start is also slow and fragile on its own (#1049, points 1 and 4). A new or erased simulator pays a full first boot (36.4 s for a new one and 39.9 s for an erase plus boot, measured on an M3 Pro with iOS 27.0), while a copy of one that booted once boots in 7.2 s. An Android reset loads a snapshot into the running emulator: one load hung for 18 minutes (#1047), a failed load wipes the disk, and creating another emulator once invalidated every other emulator's snapshot (#1048). In #1049's words: "There is also no way to prepare an emulator once (switch apps and animations off, skip a browser's first run) and keep that state across leases."

Who it is for

A team running many agents against one project, where every run needs the same prepared state. The operator who would rather set a device up once than write setup instructions for every agent. An agent that wants to start at step one of its test, not at step zero.

Every agent on a busy Mac, baseline or not, that waits for a first boot after each release.

Outcome

• An operator prepares a device on a lease they hold, by hand or with their own scripts, and saves it under a name as a baseline. Saving ends that lease. A baseline is tied to the platform, model, OS, mode and image tag of the device it was saved from.
• A lease request can name a baseline. The granted device is a copy of the baseline: its apps, data, settings, certificates and accounts are in place when the grant arrives.
• When a baseline lease is released, its device is thrown away, and the next lease naming the baseline gets a new copy: nothing from the previous lease carries over.
• Baselines can be listed with their note, spec, version, size, when they were saved and whether they are stale. Saving under an existing name replaces the baseline: leases already granted keep what they have, new leases get the new version, and the old version is deleted once nothing uses it. A baseline can be removed when no lease uses it.
• A device made from one baseline is never handed to a request for another baseline, or for none. A request with no baseline gets a plain device as today.
• A request naming a baseline that does not exist, that is stale, or that does not match the requested platform, model, OS, mode or image tag fails at once with a clear error. It never silently gets a plain device.
• Plain leases get faster too: every new or reset simulator or emulator is a copy of a device that already booted once, so no lease waits for a factory first boot after the first one of its kind, and no Android reset loads a snapshot into a running emulator.
• Through a gateway, a request naming a baseline goes only to a worker that has it, and the operator sees which workers hold which baselines.
• The console lists each worker's baselines and shows which baseline a device came from.

How it works for the user

sequenceDiagram
  actor Op as Operator
  actor Ag as Agent
  participant S as Simlock worker
  Op->>S: simlock lease --platform android
  S-->>Op: lease L1 (device D1)
  Op->>Op: install the app, sign in, turn animations off
  Op->>S: simlock baseline save checkout --lease L1 --note "app 4.2, test user"
  S-->>Op: saved checkout v1, lease L1 ended
  Ag->>S: simlock lease --platform android --baseline checkout
  S-->>Ag: lease L2: a copy of checkout v1
  Ag->>S: simlock release L2
  S->>S: destroy that copy; the next lease gets a new one
  Ag->>S: simlock lease --platform android --baseline chekout
  S-->>Ag: UNKNOWN_BASELINE, at once
  Ag->>S: simlock lease --platform android --baseline checkout --os 35
  S-->>Ag: BASELINE_MISMATCH, at once

Before:

$ simlock lease --platform android --baseline checkout
{"error":{"code":"USAGE","message":"Unknown option '--baseline'. …"}}

After:

$ simlock lease --platform android --detach
{"device":{…,"model":"Pixel 9","osVersion":"36"},"lease":{"id":"L1",…}}
$ SIMLOCK_TOKEN=<operator token> simlock baseline save checkout --lease L1 --note "app 4.2, test user"
Saved baseline checkout v1: android Pixel 9, Android 36 (google_apis), full, 4.8 GB. Lease L1 ended.
$ simlock baseline list
NAME      VERSION  PLATFORM  MODEL    OS  MODE  IMAGE        SIZE    SAVED             NOTE
checkout  1        android   Pixel 9  36  full  google_apis  4.8 GB  2026-11-02 13:10  app 4.2, test user
$ simlock lease --platform android --baseline checkout --detach
{"device":{…,"baseline":{"name":"checkout","version":1}},"lease":{"id":"L2",…}}
$ simlock lease --platform android --baseline chekout
{"error":{"code":"UNKNOWN_BASELINE","message":"no baseline named \"chekout\" on this worker"}}
$ simlock lease --platform android --baseline checkout --os 35
{"error":{"code":"BASELINE_MISMATCH","message":"baseline checkout is Android 36, the request asks for 35"}}
$ SIMLOCK_TOKEN=<agent token> simlock baseline save mine --lease L2
{"error":{"code":"FORBIDDEN","message":"Operation baseline.save requires role admin, session is agent"}}
$ SIMLOCK_TOKEN=<operator token> simlock baseline remove checkout --yes
{"error":{"code":"BASELINE_IN_USE","message":"baseline checkout is in use by lease L2"}}

Examples

A baseline name:

Which device serves which request, with baseline checkout saved from a full Pixel 9 on Android 36:

What could go wrong

• A lease named a baseline but got a device without the operator's apps. Unlikely: a baseline device is only ever a copy of that baseline.
• Two agents leasing the same baseline at once share the test account saved in it and log each other out. Likely when a team saves a signed-in account; the docs say so.
• A Mac's disk fills up because baselines are never cleaned up on their own. Possible on small disks: an Android baseline is about 5 GB.
• After an Xcode or emulator update, leases naming a baseline fail until the operator saves it again. Expected; the error and baseline list say why.

Words used

• source: a device that booted once and was shut down cleanly, kept only to be copied, never leased. Example: the device Simlock copies each time a lease asks for a plain iPhone 17 on iOS 27.0.
• seed: a source Simlock makes by itself for plain leases, one per platform, model, OS and image tag. Users never name or see it, except in doctor and disk figures.
• baseline: a source an operator saved from a lease under a name, e.g. checkout.
• version: a baseline's number, 1 at the first save and one more at each save under the same name.
• stale: a baseline whose runtime, system image or emulator changed after it was saved, so it can no longer be copied. Example: checkout after the Android 36 image was removed.
• copy: making a device from a source (iOS simctl clone; Android a copy of the AVD folder). Every lease gets a new copy; a released copy is thrown away.
• boot snapshot: the one Android memory snapshot stored with a source, so a copy boots in seconds. Replaces the per-device "clean baseline" snapshot of today.

Non-goals

• Simlock performing the setup. There is no provisioning script and no program run before a device's first boot (Lighter, faster-to-reset devices for a pool of coding agents on one Mac #1049 asks for one; it is its own request). The operator prepares the device; Simlock copies it.
• An agent saving a device back to a baseline. Only the operator saves.
• Guaranteeing that in-app state such as a signed-in session survives a boot. That is up to the app.
• Rolling a baseline back to an older version.
• Moving a baseline between workers (export and import), or keeping baselines in step across workers.
• Baselines on physical devices.
• Removing a baseline because it is old or unused. Only the operator or nuke removes one.
• Emulator RAM, cores and metrics in the config (Lighter, faster-to-reset devices for a pool of coding agents on one Mac #1049 point 3).
• Naming a baseline through agent-device. The pinned agent-device cannot send one; that is a follow-up on both sides.
• Keeping a device between leases. Every simulator and emulator now serves one lease and is thrown away; lease.identity no longer changes anything for them.

Completion conditions

• An operator leases a device, installs an app on it, and saves it as a baseline. The lease ends. simlock baseline list shows it with its platform, model, OS, mode, version and size.
• simlock lease --platform <platform> --baseline <name> is granted a device with that app installed. The agent installs nothing.
• After that lease is released, the next lease naming the baseline gets a device with the app installed and without any file or setting the previous lease changed.
• A lease with no baseline never receives a device made from one, and a lease naming one never receives a plain device or another baseline's device, even while one sits idle.
• A --baseline with a model, OS, mode or image tag the baseline was not made for fails at once, naming the mismatch. An unknown name fails at once. A stale baseline fails at once, naming why.
• Saving under an existing name leaves running leases untouched, and the next lease gets the new version.
• Removing a baseline that a lease is using is refused. Removing an unused one frees its disk and the idle devices made from it.
• On a Mac, a plain iOS lease of a kind that was leased before is granted without a factory first boot, and a plain Android reset loads no snapshot into a running emulator and never wipes.
• Through a gateway, a request naming a baseline only one worker holds is granted by that worker. One that no worker holds fails at once. simlock worker list shows each worker's baselines.
• simlock status and simlock list --devices show which baseline and version a device came from. The console lists each worker's baselines.
• simlock nuke removes baselines and seeds with every other managed device, and simlock doctor lists them with their size.
• The same request field works over the unix socket, the HTTP API, MCP and the client, and through SIMLOCK_BASELINE; the website describes it with the baseline commands.

Open questions

none

Decisions

• ADR 0061 — Every virtual device is a copy of a source, and a baseline is a named source (PR docs(adr): 0061 every virtual device is a copy of a source, and a baseline is a named source #1201): sources and seeds, how each platform copies and resets, stale sources, the baseline as a pool key, gateway routing.
• ADR 0060 — iOS slim writes launchd overrides while the simulator is shut down (PR docs(adr): 0060 iOS slim writes launchd overrides while the simulator is shut down #1194): a copy is slimmed by the same pre-boot write; ADR 0061 replaces its "reclaim still erases".

Shared values

Behaviours

Tasks

flowchart LR
  T1[#1204 iOS seeds] --> T2[#1205 Android seeds]
  T2 --> T3[#1206 save, list, remove]
  T3 --> T4[#1207 lease names a baseline]
  T4 --> T5[#1208 gateway]
  T5 --> T6[#1209 console]

• iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204 iOS: every simulator is a copy of a seed, and every virtual device serves one lease — a plain iOS lease after the first of its kind skips the factory first boot. Risk: a copy boots without Simlock's mark or slim file, and Simlock loses track of it.
• Android: every emulator is a copy of a seed in its own folder, booted from its boot snapshot #1205 Android: every emulator is a copy of a seed in its own folder, booted from a boot snapshot — no reset loads a snapshot into a running emulator or wipes. Risk: two copies of one seed are mixed up.
• An operator saves, lists and removes baselines on a worker #1206 An operator saves, lists and removes baselines on a worker. Risk: a save ends the operator's lease and loses what they prepared.
• A lease names a baseline and gets a copy of it #1207 A lease names a baseline and gets a copy of it, on every surface. Risk: a request gets a device from the wrong pool.
• A gateway routes a baseline request to a worker that holds it #1208 A gateway routes a request to a worker that holds the baseline, and shows each worker's baselines. Risk: a request naming a baseline waits instead of failing at once.
• Console: a Baselines page and a device's baseline #1209 The console lists baselines and shows a device's baseline. Risk: none beyond a wrong figure on a page.

Completion conditions by task: the first, saving, listing and removal — #1206; leasing by name, reset to the baseline, pools, fast failures, replace, status and list, every surface — #1207; plain iOS and Android leases — #1204 and #1205; nuke and doctor — #1204, #1205 and #1206; gateway — #1208; console — #1209.

Open work in the same area:

• iOS slim writes the launchd overrides before one boot, reads them back, and destroy removes their folder #1196 (ADR 0060, iOS slim before boot): changes the iOS makeReady, reclaim and destroy iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204 changes. iOS: every simulator is a copy of a seed, and every virtual device serves one lease #1204 depends on it.
• Runtime warm-pool targets: warm.set and warm.list, kept in state.db #1143 to Console: Add device… from the catalog keeps one more warm #1146 (ADR 0056, runtime warm targets): change the warm target shape. A runtime target naming a baseline is left to them; A lease names a baseline and gets a copy of it #1207 changes only learned kinds. No Depends on.
• device remove deletes an idle simulator or emulator #1134 (ADR 0055, device remove): removes one idle device; for a copy that is a normal destroy. No Depends on.
• Lease an Android device that runs as a low-RAM device #484 (low-RAM Android): another pool key on the same sameSpec and fits. Not specified yet; no Depends on.
• PR feat(android): android.emulator.hardwareKeyboard gives emulators a hardware keyboard #1082, test(e2e): find the Android SDK on Windows in the slow Android tests #1128, fix(android): stop the emulator's qemu child too when killing it on Windows #1129 (Android driver): touch src/drivers/android/index.ts; whichever merges second rebases.

Written by an agent.