Skip to content

A worker can serve enrolled phones only, and never boots a simulator or emulator #1588

Open

Description

@V3RON

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 (or ios.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 --physical is 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 --physical works exactly as today: granted, waiting, or refused when no enrolled device could match.
  • Through a gateway, a lease without --physical goes 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]
Loading

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_MODEL on 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>.virtualDevices is false on this worker.
  • plain lease: a lease request without --physical.
  • idle device: a virtual device no lease holds and no operation has claimed, ready or shutdown.
  • 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 catalog and by a gateway to route.

Non-goals

  • Starting Android with only adb installed: the full SDK (emulator, avdmanager, sdkmanager, adb) stays required. A later request.
  • Serving a plain lease with a phone.
  • Allowing 0 for the capacity limits.
  • Refusing simlock component install on 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 answers UNKNOWN_MODEL with the phones-only message at once, and no emulator is created, booted or downloaded for it.
  • With it, an Android --physical lease 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 catalog shows the phones-only line for that platform, and catalog.get carries virtualDevices: false.
  • ios.virtualDevices: false does 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 --physical is 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 --physical never 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 defaultMode and defaultModels, 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, default true (maintainer, 2026-11-16).
  • Decided in the session: the refusal is UNKNOWN_MODEL with 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 install stays allowed (maintainer, 2026-11-16).
  • Decided in the session: baseline list is 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 --physical request 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 shutdown and the next start tries again.
  • Decided in the session: the gateway's merged catalog carries virtualDevices: false for a platform only when every worker reporting it does, so simlock catalog through 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

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

    @V3RON
    ContributorAuthor

    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.

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