Repository navigation
Description
Request: #1181
Problem
In the reporter's words: "I want this worker to lease only physical Android devices that I've enrolled with simlock device add --platform android <serial>. If none is plugged in, an Android lease should fail instead of falling back to booting an emulator."
"There doesn't seem to be a way to configure this." Setting capacity.config.limits.android.maxDevices and maxRunning to 0 is refused, because both must be 1 or more, "and I don't know whether these limits also count physical devices." They do not: only simulators and emulators count.
"I test on real Android hardware and never want an emulator on this machine. Emulators use a lot of RAM (the default budget is 4 GiB per device), and a test that silently runs on an emulator when I expected a phone gives misleading results. … I often just ask the agent to test using simlock, I don't want it to boot a emulator whenever I forgot to specifically ask for a physical phone."
Today a lease without --physical always gets a simulator or emulator, and the warm pool boots them on its own.
Who it is for
An operator who runs a worker for real phones only, alone or joined to a gateway, with agents that lease through it and sometimes forget --physical. On iOS, the same operator with iPhones and iPads only.
Outcome
- The operator turns virtual devices off for one platform with one setting:
simlock config set android.virtualDevices false(orios.virtualDevices), then a restart. - From then on that worker never creates, boots or keeps a simulator or emulator of that platform.
- A lease of that platform without
--physicalis refused at once with a message that says the worker serves enrolled devices only and to pass--physical. It never waits and never downloads. - A lease with
--physicalworks exactly as today: granted, waiting, or refused when no enrolled device could match. - Through a gateway, a lease without
--physicalgoes to a worker that still makes virtual devices. When no such worker has the platform, it gets the same message.
How it works for the user
flowchart TD
A[Operator: config set android.virtualDevices false, restart] --> B[Worker deletes its idle emulators]
C[Agent: simlock lease --platform android] --> D{--physical?}
D -- no --> E[UNKNOWN_MODEL: only enrolled devices, pass --physical]
D -- yes --> F{An enrolled phone could match?}
F -- no --> G[UNKNOWN_MODEL: no enrolled device can match]
F -- yes --> H{Free and plugged in?}
H -- yes --> I[Phone granted]
H -- no --> J[Waits, or NO_CAPACITY with --no-wait]
Before:
$ simlock config set capacity.config.limits.android.maxDevices 0
{"error":{"code":"USAGE","message":"Invalid config after setting capacity.config.limits.android.maxDevices: Invalid config value for \"capacity.config.limits.android.maxDevices\": expected a positive integer"}}
$ simlock config set android.virtualDevices false
{"error":{"code":"USAGE","message":"Invalid config after setting android.virtualDevices: Unknown config key: \"android.virtualDevices\""}}
$ simlock lease --platform android
{"leaseId":"…","device":{"platform":"android","model":"Pixel 9","physical":false,…}}
After:
$ simlock config set android.virtualDevices false
Updated android.virtualDevices in /Users/alex/.simlock/config.json; takes effect on daemon restart.
$ simlock daemon stop && simlock daemon start
$ simlock lease --platform android
{"error":{"code":"UNKNOWN_MODEL","message":"This worker serves only enrolled physical android devices (android.virtualDevices is false); pass --physical to lease one"}}
$ echo $?
12
$ simlock lease --platform android --physical
{"leaseId":"…","device":{"platform":"android","model":"Pixel 8","physical":true,"class":"phone",…}}
$ simlock catalog --platform android
android:
Virtual devices: off (android.virtualDevices is false); only enrolled physical devices are leased
Runtimes: (none) (default: (none))
Models: (none)
Images: (none)
Examples
On a worker with android.virtualDevices: false, ios.virtualDevices left at true, and one enrolled Pixel 8 on API 35:
| Request | Today | After |
|---|---|---|
--platform android |
emulator granted | UNKNOWN_MODEL, phones-only message, at once |
--platform android --device "Pixel 9" |
emulator granted | UNKNOWN_MODEL, phones-only message |
--platform android --os ">=34" |
emulator granted | UNKNOWN_MODEL, phones-only message |
--platform android --image-tag google_apis_playstore |
emulator, or RUNTIME_MISSING |
UNKNOWN_MODEL, phones-only message |
--platform android --allow-download --os 36 |
downloads, then emulator | UNKNOWN_MODEL, phones-only message; nothing downloads |
--platform android --baseline checkout |
copy of the baseline | UNKNOWN_MODEL, phones-only message |
--platform android --no-wait |
emulator, or NO_CAPACITY |
UNKNOWN_MODEL, phones-only message |
--platform android --physical |
Pixel 8 granted | Pixel 8 granted |
--platform android --physical --device "Pixel 7" |
UNKNOWN_MODEL, no enrolled device can match |
same |
--platform android --physical --no-wait, Pixel 8 leased |
NO_CAPACITY |
same |
--platform android --physical --image-tag x |
BAD_REQUEST |
same |
--platform ios |
simulator granted | simulator granted |
simlock config set android.virtualDevices false |
refused, exit 2: Unknown config key: "android.virtualDevices" |
written; takes effect on daemon restart |
simlock config set android.virtualDevices no |
refused, exit 2: unknown key | refused, exit 2: expected a boolean |
simlock config set capacity.config.limits.android.maxDevices 0 |
refused, exit 2: expected a positive integer |
same |
What could go wrong
- An agent that never reads errors keeps retrying a plain lease. Likely only for scripts; the message names the fix.
- An operator turns the switch off on a worker that also serves emulator users. They see
UNKNOWN_MODELon their next lease. Likely once; the message names the key. - Idle emulators are deleted at the restart. An operator who expected them to stay loses nothing that a later lease would not make again; baselines stay.
- Behind an older gateway, the plain lease gets the old "no model of class phone is listed" message.
Words used
- virtual device: a simulator or emulator Simlock makes itself, e.g. an Android emulator copied from a seed.
- physical device (phone): a real device an admin enrolled with
simlock device add, e.g. a Pixel 8 on USB. iPads count too. - phones-only platform: a platform whose
<platform>.virtualDevicesisfalseon this worker. - plain lease: a lease request without
--physical. - idle device: a virtual device no lease holds and no operation has claimed,
readyorshutdown. - warm pool: what keeps idle virtual devices booted ahead of leases, from configured targets and kinds it learned.
- catalog: the list of models, runtimes and images a worker reports, read by
simlock catalogand by a gateway to route.
Non-goals
- Starting Android with only
adbinstalled: the full SDK (emulator, avdmanager, sdkmanager, adb) stays required. A later request. - Serving a plain lease with a phone.
- Allowing
0for the capacity limits. - Refusing
simlock component installon a phones-only platform: an operator may still install and remove images and runtimes. - Changing the setting without a restart.
- Deleting saved baselines or seeds when the switch is turned off.
- Marking baselines as unusable in
simlock baseline list.
Completion conditions
- With
android.virtualDevices: false, every plain Android lease in Examples answersUNKNOWN_MODELwith the phones-only message at once, and no emulator is created, booted or downloaded for it. - With it, an Android
--physicallease is granted, waits and is refused exactly as on a worker without it. - With it, a configured Android warm target and an Android learned kind boot nothing, and an iOS target still fills.
- With it, the worker's idle Android emulators are gone after a restart, a leased one is deleted at its release, and saved baselines are still listed.
simlock catalogshows the phones-only line for that platform, andcatalog.getcarriesvirtualDevices: false.ios.virtualDevices: falsedoes the same for iOS.- Through a gateway whose only Android worker is phones-only, a plain Android lease gets the gateway's phones-only message, and
--physicalis routed to that worker. - The configuration reference, the physical devices page, the errors pages and the gateway routing page describe the setting.
Open questions
Decisions
- ADR 0078 — A worker may serve a platform's enrolled phones only (PR docs(adr): propose 0078, a worker may serve a platform's enrolled phones only (#1588) #1592): the per-platform key, what it turns off, the refusal, and the catalog field a gateway reads.
- ADR 0022 — A physical device is a second device type: "a lease without
--physicalnever gets a physical device" stays true; narrowed by 0078. - ADR 0009 — Gateway routing: §4's table gains the phones-only answer (0078 §3).
- ADR 0065 — A driver owns its config keys: this key is core's, beside
defaultModeanddefaultModels, because core, leasing and the gateway act on it and no driver does. - Decided in the session: both platforms, one key each (maintainer, 2026-11-16).
- Decided in the session: a plain lease on a phones-only platform is refused, never served by a phone (maintainer, 2026-11-16).
- Decided in the session: the full Android SDK stays required (maintainer, 2026-11-16).
- Decided in the session: the key is
<platform>.virtualDevices, a boolean, defaulttrue(maintainer, 2026-11-16). - Decided in the session: the refusal is
UNKNOWN_MODELwith its own message, no new code (maintainer, 2026-11-16). - Decided in the session: at start, idle virtual devices of the platform are deleted, leased ones run to their release, baselines stay (maintainer, 2026-11-16).
- Decided in the session: a gateway gives the same message, read from a field on each worker's catalog entry, one protocol bump (maintainer, 2026-11-16).
- Decided in the session:
component installstays allowed (maintainer, 2026-11-16). - Decided in the session:
baseline listis unchanged; a lease naming a baseline of that platform gets the phones-only refusal, because a mark on each baseline would change the baseline schema for a message the lease already gives. - Decided in the session: the refusal happens in leasing's one resolve step, before the baseline branch, so lease requests, warm targets and learned kinds are all refused by the same check, and the warm pool needs no change of its own.
- Decided in the session: the worker's catalog entry for a phones-only platform keeps the platform with empty lists, because a gateway routes a
--physicalrequest only to a worker whose catalog has the platform (src/gateway/routing/serviceability.ts:207). - Decided in the session: learned kinds of that platform are forgotten by the existing catalog check, since the empty catalog lists none of them; they are learned again once the key is back on.
- Decided in the session: the setting takes effect on restart, as every key does.
- Decided in the session: a delete that fails at start is logged and the start goes on; the device stays
shutdownand the next start tries again. - Decided in the session: the gateway's merged catalog carries
virtualDevices: falsefor a platform only when every worker reporting it does, sosimlock catalogthrough a gateway says "off" only when no worker would serve a plain lease.
Behaviours
| Id | Behaviour (invoker, action, what it sees) | Seam | Cases | Task |
|---|---|---|---|---|
| B1 | An operator sets <platform>.virtualDevices (I1): config set accepts a boolean and refuses anything else with the boolean message; config get shows the value, true when unset |
loadConfig with the driver sections, and simlock config set / config get |
android false; ios false; unset (true); no (refused, expected a boolean); 0 (refused); a gateway's config holding it (ignored with the worker-key warning) |
T1 |
| B2 | An agent sends a plain lease on a phones-only platform: it is refused at once with I2, before any catalog read, download or queue entry; the other platform is served as today | lease.request through the worker dispatcher, with the fake drivers |
every plain row of Examples (no model, named model, OS range, image tag, allowDownload, baseline, noWait); iOS --mode slim with except; the other platform still granted; the fake driver's resolveSpec, listCatalog and installComponent never called |
T1 |
| B3 | An agent sends a --physical lease on a phones-only platform: granted, waiting or refused exactly as on any worker |
lease.request through the worker dispatcher, with the fake drivers |
free enrolled phone (granted); every match leased (waits); same with noWait (NO_CAPACITY); no enrolled match (UNKNOWN_MODEL, today's message) |
T1 |
| B4 | The warm pool runs on a worker with a phones-only platform: that platform's configured targets report unresolvable with I2's message and boot nothing, its learned kinds are forgotten, reserveRunning holds nothing; the other platform fills |
core with leasing, the warm-pool converger, fake drivers | configured Android target; Android learned kind from before the switch; reserveRunning.android: 2; iOS target (filled) |
T1 |
| B5 | The worker starts with a platform phones-only: every idle virtual device of that platform is deleted (a ready one shut down first) with its usual device.deleted, a leased one is kept and deleted at its release, phones and the other platform are untouched; a delete that fails is logged (I6) and the start goes on |
daemon start, core.converge (StartupConverger), fake drivers |
ready idle; shutdown idle; leased (kept, then deleted at release); claimed (left); enrolled phone (untouched); iOS idle device (kept); fake driver's destroy throws (I6 logged, device shutdown, start completes) |
T1 |
| B6 | A caller reads the catalog of a phones-only worker: the platform's entry has empty lists and virtualDevices: false (I4, I5) without asking the driver, and simlock catalog prints I7 |
catalog.get through the dispatcher; simlock catalog |
--platform android; no platform (both entries, iOS full); --json; the fake driver's listCatalog never called for Android |
T1 |
| B7 | An operator manages components on a phones-only platform: component install, list and remove work as today |
component.install, component.list, component.remove through the dispatcher, fake drivers |
install an Android image; list; remove it | T1 |
| B8 | An agent sends a plain lease through a gateway: when every known worker with the platform reports virtualDevices: false, it fails at once with I3; when one does not, it is routed there; a --physical lease still reaches a phones-only worker |
gateway assess and select over worker views (src/gateway/routing), and lease.request through the gateway dispatcher with fake links |
one phones-only worker (I3); phones-only plus an emulator worker (routed to the emulator worker); phones-only worker and a worker without the field (routed to the second); one worker without the field and no models (today's UNKNOWN_MODEL message); --physical to the phones-only worker (granted) |
T2 |
| B9 | A caller reads the catalog through a gateway: the merged entry carries virtualDevices: false only when every worker reporting the platform does |
aggregateCatalog (src/gateway/aggregate.ts), catalog.get through the gateway |
two phones-only workers (false); one phones-only and one emulator worker (absent, the emulator worker's lists) | T2 |
Stored state
| Id | What and where | Created, changed, deleted by | Listed or swept by | A restart mid-step leaves | Schema step | Task | Used by |
|---|---|---|---|---|---|---|---|
| S1 | ios.virtualDevices and android.virtualDevices in the user's config.json (I1) |
the operator, by simlock config set or by hand; read once at start |
config get; daemon.started's config snapshot |
— (read at start only) | none | T1 | T2 |
The devices B5 deletes are today's registry rows and driver folders, deleted by today's ManagedDeviceLifecycle.shutdown and destroy; a restart in the middle leaves a shutdown row that the next start deletes.
Interfaces
| Id | What | Shape and bounds | Errors and limits | Where | Task | Used by |
|---|---|---|---|---|---|---|
| I1 | Config keys ios.virtualDevices, android.virtualDevices |
boolean, optional, default true; core keys of the platform section (Config["ios"], Config["android"]), beside defaultMode and defaultModels; worker only |
a non-boolean fails the load as every boolean key does (booleanValue: Invalid config value for "<key>": expected a boolean, config set exit 2); on a gateway, the worker-key warning of src/core/config-role-checks.ts:96 |
src/core/config-types.ts, config-defaults.ts, config-validators.ts; website reference/configuration.mdx |
T1 | T2 |
| I2 | Worker refusal VirtualDevicesOffError, a subclass of UnknownModelError carrying the request's model or class |
code UNKNOWN_MODEL (exit 12, HTTP 422), details { platform, model? , class? } as today; message This worker serves only enrolled physical <platform> devices (<platform>.virtualDevices is false); pass --physical to lease one |
thrown by AcquisitionSpecResolver.resolveSpec before the baseline branch, so resolve (warm targets) answers refusal unknown-model with the same message; mapped by the existing UnknownModelError branch of src/daemon/error-code.ts:129 |
src/leasing/acquisition-spec-resolver.ts, acquisition-errors.ts |
T1 | — |
| I3 | Gateway refusal, a row of assessLeading after the NO_DRIVER row, for a plain request only |
code UNKNOWN_MODEL, reason unresolvable-spec, details { platform, model?, class? }; message Every worker with <platform> serves only enrolled physical <platform> devices (<platform>.virtualDevices is false); pass --physical to lease one |
applies when no known worker lists the model and every known worker whose catalog has the platform reports virtualDevices: false |
src/gateway/routing/serviceability.ts |
T2 | — |
| I4 | DriverCatalog.virtualDevices(platform): boolean, and the option virtualDevices: Partial<Record<Platform, boolean>> it is built with in createCore from I1 |
false only for a platform whose key is false; listCatalog for that platform answers { platform, models: [], runtimes: [], modelRuntimes: {}, modelAliases: {}, modelClasses: {}, classDefaults: {}, virtualDevices: false } and never calls the driver's listCatalog |
— | src/core/driver-catalog.ts, src/core/create-core.ts (CoreConfig gains ios and android), leasing's catalog port (src/leasing/acquisition-ports.ts:62) |
T1 | T2 |
| I5 | Catalog entry field virtualDevices on platformCatalogSchema |
z.literal(false).optional(); absent means virtual devices are served; bumps the protocol by one |
an older gateway strips it and keeps today's answers | src/contract/status-schemas.ts, src/contract/protocol.ts |
T1 | T2 |
| I6 | Startup's delete of an idle device on a phones-only platform | log at warn: Could not delete an idle device at start with { deviceId, platform, error } |
the device stays shutdown; the next start tries again |
src/core/startup-converger.ts, wired in src/core/create-core.ts |
T1 | — |
| I7 | simlock catalog's line for an entry with virtualDevices: false, first under the platform name |
Virtual devices: off (<platform>.virtualDevices is false); only enrolled physical devices are leased |
— | src/cli/commands/catalog.ts |
T1 | T2 |
Existing code
Commit 5e639b4.
Searches: listCatalog\( 20 hits outside tests; resolveSpec\( 25; \.provision\( 12 (src/core/device-provisioner.ts:137 and the leasing and warm-pool callers through it); bootWarm\( 2; platformCatalogSchema 6; NO_DRIVER and UNKNOWN_MODEL in src/gateway/routing; virtualDevices 58 (all the registry's snapshot.virtualDevices, none a config key).
| Id | Code (path:line) | Today | With this feature | Handled by |
|---|---|---|---|---|
| X1 | src/core/config-validators.ts:255-263, src/core/config-types.ts:166-172, src/core/config-defaults.ts:152-153 |
the platform sections hold core's defaultMode (iOS) and defaultModels, then the driver's keys |
virtualDevices added to both |
I1, B1 |
| X2 | src/leasing/acquisition-spec-resolver.ts:53-72 |
resolveSpec takes the baseline branch first, then resolves a model, class or range |
I2 is checked first, through catalog.virtualDevices |
I2, B2 |
| X3 | src/leasing/acquisition-spec-resolver.ts:287-305, :339-343 |
resolve (warm targets and learned kinds) calls resolveSpec with downloads off; UnknownModelError maps to unknown-model |
the refusal reaches the pool as unknown-model with I2's message; no boot |
B4 |
| X4 | src/leasing/acquisition-workflow.ts:116-131 |
a --physical request skips spec resolution and checks enrolled devices |
unchanged | B3 |
| X5 | src/core/driver-catalog.ts:195-215 |
listCatalog asks every driver and adds classDefaults |
an off platform answers I4's empty entry without the driver | I4, B6 |
| X6 | src/core/warm-pool/catalog-check.ts:43-53 |
gone forgets a learned kind the latest catalog answer does not list |
forgets every kind of the off platform | B4 |
| X7 | src/core/startup-converger.ts:46-88, src/core/create-core.ts:390-405 |
startup recovers interrupted reclaims, then deletes spent shutdown devices on readable platforms |
a third step deletes every idle device of an off platform, ready ones through ManagedDeviceLifecycle.shutdown (src/core/managed-device-lifecycle.ts:168) then destroy (:190) |
B5, I6 |
| X8 | src/core/reclaim-coordinator.ts:305-312 |
deleteSpent refuses a device that mayBeGranted, so it cannot delete a never-leased idle one |
not used for B5 | B5 |
| X9 | src/contract/status-schemas.ts:273-292, src/contract/protocol.ts:13 |
the catalog entry has no field about virtual devices; protocol range { min: 89, max: 89 } |
I5's field; max +1, min unchanged | I5 |
| X10 | src/cli/commands/catalog.ts:37-78 |
prints runtimes, models and images per platform, (none) when empty |
prints I7 first for an off entry | I7, B6 |
| X11 | src/gateway/routing/serviceability.ts:197-235 |
assessLeading: NO_DRIVER when no known worker has the platform, then the physical branch, then UNKNOWN_MODEL "listed by any worker in the fleet" |
I3's row before the generic model row, plain requests only | I3, B8 |
| X12 | src/gateway/routing/stages/can-serve.ts:4-14, src/gateway/routing/request-match.ts:183-186 |
a worker with the platform but no models answers unknown-model; a --physical request needs only enrolled devices and the platform entry |
unchanged: a phones-only worker is passed over for plain requests and picked for --physical |
B8 |
| X13 | src/gateway/aggregate.ts:247-275, :365-375 |
the merged entry is the union of the workers' lists | carries I5's false only when every worker's entry does |
B9 |
| X14 | src/daemon/dispatcher-components.ts:107-115 |
component.install refuses only under downloads.policy: "never" |
unchanged | B7 |
| X15 | src/core/doctor.ts:507-526 and src/core/doctor-findings.ts:233 |
doctor reports a configured warm target it could not meet | an Android target on an off platform is reported as unreachable, with the pool's refusal | B4 |
| X16 | src/core/capacity/devices.ts:21-25 |
capacity counts only virtual devices | unchanged: phones never counted; the off platform has none | — |
| X17 | website/src/content/docs/docs/using-devices/physical-devices.mdx:43-59, using-devices/errors.mdx:40-54, reference/errors.mdx:51, reference/configuration.mdx:205-224, the gateway routing page |
describe plain and physical leases, UNKNOWN_MODEL, and the platform keys |
a "Serve enrolled devices only" section, the key rows, and the new UNKNOWN_MODEL cause on each page |
T1 (worker pages), T2 (gateway routing page) |
Tasks
Written after the design check and approval.
Written by an agent.
Activity
V3RON commentedon Nov 16, 2026
Design posted: every business section, Decisions (ADR 0078, PR #1592), Behaviours B1–B9, Stored state S1, Interfaces I1–I7 and Existing code X1–X17. Tasks come after the design check and approval.
Written by an agent.