Repository navigation
Description
Problem
Slim turns off whole categories of simulator services (ios.slim.categories). Operators need finer control in both directions:
- keep a few services running while the rest of their category stays off (Keep individual services enabled in slim mode #1556: "We need a few services such as push, assets and StoreKit while keeping the rest of their slim categories disabled");
- turn off a service that no category holds (Slim: opt-in control for simulator diagnosticd #1552:
com.apple.diagnosticd, 7–11% of a core per booted simulator on one x86 VM with iOS 26.5; it must stay opt-in because without itlog streaminside the simulator breaks).
Who it is for
Operators of a shared iOS worker that runs many slim simulators for coding agents, where CPU and memory are tight.
Outcome
In the worker config, an operator names single launchd services that slim keeps running (ios.slim.include) or turns off (ios.slim.exclude), beside the categories. Every slim device that worker prepares from then on boots that way. Nothing changes for a lease, a gateway or a client.
How it works for the user
flowchart TD
A["operator edits config.json:<br/>ios.slim.include / exclude"] --> B{daemon start}
B -->|a name in both lists,<br/>or not a list of strings| C["start fails:<br/>Invalid config value for ios.slim"]
B -->|ok| D[slim lease or warm boot]
D --> E["services off = categories − lease --except<br/>+ exclude − include"]
E --> F[boot once, read back]
F -->|every service as written| G[device mode slim]
F -->|a service not as written| H[device mode full]
F -->|nothing is off| H
Before (config.json):
{ "ios": { "defaultMode": "slim", "slim": { "include": ["com.apple.apsd"] } } }The daemon log says Unknown config key: "ios.slim.include" and the key is ignored: push stays off with the store category.
After:
{ "ios": { "defaultMode": "slim", "slim": {
"include": ["com.apple.apsd"],
"exclude": ["com.apple.diagnosticd"] } } }The daemon logs no warning. A slim lease's simulator runs apsd and no diagnosticd; the rest of every category stays off.
A name in both lists fails the config load, so the daemon does not start; simlock daemon start prints the error line with the message Invalid config value for "ios.slim": expected no service in both include and exclude (com.apple.apsd).
Examples
What a slim device turns off (worker config → services off; "today" is the same config on main, where both keys are unknown and ignored):
categories |
include |
exclude |
Lease --except |
Today | After |
|---|---|---|---|---|---|
| unset | — | — | — | every category, slim |
same |
| unset | com.apple.apsd |
— | — | every category, apsd off |
every category but apsd |
[] |
— | com.apple.diagnosticd |
— | nothing off, full |
only diagnosticd, slim |
["widgets"] |
— | com.apple.diagnosticd |
— | widgets |
widgets + diagnosticd |
["store"] |
every label of store |
— | — | store |
nothing off, full |
["store","other"] |
— | com.apple.diagnosticd |
store,other |
nothing off, full |
only diagnosticd, slim |
["store"] |
— | one label of store |
store |
store kept |
store kept, that label runs too |
| unset | — | com.apple.gamed |
— | gamed runs (never disabled) |
gamed off |
| unset | — | com.apple.no-such-thing |
— | — | written off; nothing to stop; slim |
What the config load says:
| Value | Today | After |
|---|---|---|
"include": ["com.apple.apsd"] |
logged as unknown, ignored | accepted |
"include": [] |
logged as unknown, ignored | accepted (nothing changes) |
"exclude": ["a", "a"] |
logged as unknown, ignored | accepted (one name) |
"include": ["x"], "exclude": ["x"] |
logged as unknown, ignored | load fails |
"exclude": "com.apple.diagnosticd" |
logged as unknown, ignored | load fails: expected an array of strings |
"exclude": [""] |
logged as unknown, ignored | load fails: expected an array of strings |
"exclude": ["store"] (a category name) |
logged as unknown, ignored | accepted as a service name; matches no service |
What could go wrong
- An operator misspells a service name: nothing is turned off or kept, and Simlock says nothing. Likely now and then; the docs say so.
- An operator excludes a service the simulator needs to boot: every slim boot on that worker fails or grants
full. Rare; the config is theirs. - A name taken out of
excludestays off in copies of a baseline saved before this feature shipped. Rare; putting it inincludefixes it.
Words used
- service (launchd label): the name launchd gives a background program inside the simulator, e.g.
com.apple.diagnosticd. - category: a named group of services slim turns off together, e.g.
store. - managed label: a service whose on/off line Simlock writes into the simulator's
disabled.pliston every slim boot; any other line in that file is left as it is. - readback: after the boot, Simlock asks launchd which services are disabled and compares with what it wrote.
--except: a lease's list of categories that run for that lease only.- record of named services: a small file Simlock keeps next to
disabled.plistwith theincludeandexcludenames it last wrote, so a name taken out of both lists is turned back on, e.g.["com.apple.diagnosticd"].
Non-goals
- Service names on a lease:
--exceptstays categories-only. - Advertising
includeorexcludein the catalog, or routing by them on a gateway. - Checking that a name is a real service of the runtime.
- Turning a service back on in baselines saved before this feature shipped (they have no record).
- Console editing of these keys.
Completion conditions
- A worker with
ios.slim.exclude: ["com.apple.diagnosticd"]andcategories: []grants a slim lease aslimdevice in which nodiagnosticdruns (on a Mac, real simulator). - A worker with
ios.slim.include: ["com.apple.apsd"]andcategoriesunset grants a slim device whoselaunchctl print-disabled systemshowsapsdnot disabled and every other category label disabled (on a Mac, real simulator). - A worker restarted with
com.apple.diagnosticdtaken out ofexcludeprepares its surviving idle simulators withdiagnosticdon. - A config with one name in both lists fails the daemon start with the message of I1.
- The configuration reference lists both keys and says that
categoriesandexcludeturn services off andincludekeeps them running.
Open questions
none
Decisions
- ADR 0083 — A worker may turn single slim services on or off beside its categories: the two lists, how they combine with categories and
--except, the readback rule, and when a device isslim. - ADR 0060 — iOS slim writes launchd overrides while the simulator is shut down: the file, the readback and its table stay; 0083 narrows §1 and §2.
- ADR 0066 — A slim lease may keep named categories running: the strict rule stays for
--exceptonly. - Decided with the maintainer: an
includeorexcludeservice not read back as written follows today's slim rule (full; a readback that cannot run grantsslim), not--except's failing boot, because a plain slim boot that fails is not retried and a slow readback would fail every boot on that worker. - Decided in the session: a device is
slimwhen at least one service is written off, becausecategories: []with anexcludeis Slim: opt-in control for simulator diagnosticd #1552's setup. - Decided in the session: a lease's
--exceptcategory wins overexcludefor its own services, because the lease asked for them running and ADR 0066 already lets a kept category win. - Decided in the session:
excludewins over simslim's never-disable list (assistantd,gamed,sharingd), because the operator named the service. - Decided in the session: any non-empty string is a name, duplicates are one name, and a typo is not caught, because launchd reads back whatever the file says and the shape was agreed as "any service name".
- Decided in the session:
device.slimmedkeeps its fields;labelCountcounts excluded services too andcategoriesstays the categories, because the event's consumers read counts, not lists. - Decided with the maintainer: Simlock keeps a record of the
includeandexcludenames it wrote beside each simulator'sdisabled.plist(S2), and turns a recorded name it no longer manages back on at the next prepare, because otherwise an idle simulator that survives a restart, or a baseline's copy, keeps a revertedexcludeoff with no warning; the file also holds lines the runtime wrote, so Simlock cannot reset lines without knowing which are its own. - Decided in the session: the both-lists check runs on the merged config through a
checkon the driver's config entry, as modules already have, becauseconfig.jsonand the CLI overrides are validated one layer at a time.
Behaviours
| Id | Behaviour (invoker, action, what it sees) | Seam | Cases | Task |
|---|---|---|---|---|
| B1 | An operator starts a worker with ios.slim.include and ios.slim.exclude; the config loads with both, or fails with I1's message. |
configFromLayers (src/core/config.ts:125) |
both lists set; one empty list; a duplicate in one list; a name in both (fails, names it); include in config.json and the same name in exclude in the overrides layer (fails); a string instead of a list (fails); an empty string (fails); config get ios.slim shows both |
#1650 |
| B2 | A slim prepare boot writes each managed label as S1's rule says. |
IosSimctlDriver.makeReady (src/drivers/ios/index.ts:372), fake simctl and filesystem |
include label of a slimmed category → false; exclude label in no category → true; exclude of a never-disable label → true; --except category with one of its labels in exclude → false; a line the file had for an unmanaged label is kept; a name in S2's record and in neither list now → false, and the record is rewritten to the current names; no record → treated as empty, not logged; a record that cannot be read as a list of strings → treated as empty, logged; a failed record write counts as a failed overrides write (ADR 0060 §2); a record that would not change is not written; a provisioned copy gets its source's record with its plist |
#1650 |
| B3 | That boot's readback grants the mode of I2. | IosSimctlDriver.makeReady |
every label as written → slim and device.slimmed with labelCount counting the exclude label; an exclude label read back enabled → full, slim skipped logged; an include label read back disabled on a lease with no --except → full, no throw; readback fails → slim, logged; categories: [] + exclude → slim; nothing written off (include covers the slim set, or --except covers it with no exclude) → full, no device.slimmed; categories: [], no exclude → full, slim skipped as today |
#1650 |
| B4 | A lease with --except on a worker with include/exclude still fails its boot only on its kept categories, as today. |
IosSimctlDriver.makeReady |
a kept label read back disabled → KeptCategoriesError; an exclude label read back enabled → full, no throw |
#1650 |
| B5 | An operator reads the configuration reference and the slim guide and finds both keys. | src/core/config-reference.test.ts (walks the validator shape) |
the reference table lists ios.slim.include and ios.slim.exclude |
#1650 |
| B6 | On a Mac, a slim lease on a worker with categories: [] and exclude: ["com.apple.diagnosticd"] gets a slim simulator in which no diagnosticd process runs; on a worker with categories unset and include: ["com.apple.apsd"], the readback shows apsd not disabled and every other category label disabled. |
slow lane, real simulator | the two leases, iOS 26.4 or newer | #1650 |
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 | The lines of a slim simulator's /private/var/tmp/com.apple.CoreSimulator.SimDevice.<udid>/disabled.plist (ADR 0060). Managed labels are every category label, the never-disable labels, every include and exclude name, and every name in S2's record. Each is written, in this order of precedence (last wins): false (so a recorded name in neither list goes back on); true for a label of a category in categories and not in the lease's --except, never-disable labels excepted; true for an exclude name; false for an include name; false for a label of a --except category. |
SlimBoot.writeOverrides on every prepare of a slim spec; copied from a source by copyOverrides; removed by destroy |
— (as today) | the file as written, or the old one; the next prepare writes it again |
none | #1650 | — |
| S2 | Record of named services: simlock-managed.json in the same folder as S1, a JSON array of the include and exclude names last written, sorted, mode 0644. |
SlimBoot.writeOverrides after the plist, atomically, on a prepare of a slim spec when its contents change (an empty list with no file is no change, so a worker without the keys writes none); copied with the plist by copyOverrides; removed with the folder by destroy |
— | the plist written and the old record: the old record still lists every name the plist may hold off, so the next prepare handles it |
none | #1650 | — |
Interfaces
| Id | What | Shape and bounds | Errors and limits | Where | Task | Used by |
|---|---|---|---|---|---|---|
| I1 | Worker config keys ios.slim.include, ios.slim.exclude |
each optional; an array of non-empty strings, any characters; unset is []; duplicates count once. Worker config only (driver keys). |
a value that is not an array of non-empty strings: Invalid config value for "ios.slim.<key>": expected an array of strings (today's stringArray). A name in both: Invalid config value for "ios.slim": expected no service in both include and exclude (<names, comma-separated>). Both fail the config load. |
src/drivers/ios/definition.ts |
#1650 | — |
| I2 | Device mode of a slim prepare boot |
slim when at least one managed label is written true, the write was ok and every managed label reads back as written; otherwise ADR 0060 §2's table. No label written true → full, no device.slimmed; with neither categories nor exclude known, slim skipped is logged as today. --except leases keep ADR 0066 §2 for their kept labels only. |
no new error | src/drivers/ios/slim-boot.ts |
#1650 | — |
| I4 | DriverConfigEntry.check |
optional (section, config) => void, run on the merged config after both layers, as runModuleChecks runs a module's; throws ConfigError |
the both-lists message of I1 | src/core/config-types.ts, src/core/config-role-checks.ts |
#1650 | — |
| I3 | device.slimmed |
fields unchanged; labelCount is the managed labels written true, exclude names included |
— | EVENTS.md device.slimmed |
#1650 | — |
Existing code
Commit 1cd9315.
Searches: rg -n "slim" src --include=*.ts minus tests (43 files; read the iOS driver's slim-*, definition.ts, catalog.ts, seeds.ts, index.ts); rg -n "copyOverrides|writeOverrides|KeptCategoriesError" src (8 hits); rg -n "validatorShape" src (2 files); rg -ln "slim" website/src/content/docs (15 files; read reference/configuration.mdx, using-devices/choosing-a-device.mdx, reference/events.mdx, reference/errors.mdx); rg -ln slim ui/src (no config editor).
| Id | Code (path:line) | Today | With this feature | Handled by |
|---|---|---|---|---|
| X1 | src/drivers/ios/definition.ts:12-17, :49 |
slim is {categories, bootTimeoutMs}; objectValidator warns on any other key (src/core/validation.ts:41) |
adds include, exclude to the objectValidator shape (so validatorShape, src/core/validation.ts:23-51, still lists them for the reference test) and the both-lists check as the entry's I4 check |
B1, B5 |
| X11 | src/core/config-types.ts:266-275 DriverConfigEntry; src/core/config-role-checks.ts:133-136 runModuleChecks; src/core/config.ts:150-160 (layers validated one at a time) |
a driver entry has no check on the merged config; a module entry has check |
gains I4, run where module checks run | B1 |
| X2 | src/drivers/ios/slim-labels.ts:349-364 overridesFor |
category labels and never-disable labels; kept categories win | takes include and exclude in S1's order |
B2 |
| X3 | src/drivers/ios/slim-boot.ts:161-168 |
no known category → no-categories, no write, full, slim skipped |
no-categories only when no category and no exclude name |
B3 |
| X4 | src/drivers/ios/slim-boot.ts:245-246 |
an --except covering the slim set → full, no event |
no label written true → full, no event |
B3 |
| X5 | src/drivers/ios/slim-boot.ts:206, :217; slim-except.ts:33-43 |
strict failures when kept is not empty; kept = the lease's --except categories |
unchanged; include names never join kept |
B4 |
| X6 | src/drivers/ios/slim-boot.ts:232-240 |
a managed label not as written → full |
the same, now over include/exclude names too |
B3 |
| X7 | src/drivers/ios/seeds.ts:172, :249 copyOverrides |
a baseline or seed's file is copied into each copy before its first boot | copies S2 beside the plist; a source saved before this feature has none, so a dropped name stays true in its copies (known gap, manual) |
B2 |
| X8 | src/drivers/ios/catalog.ts:82, :206 |
checkExcept and slimCategories from categories |
unchanged: no catalog or routing change | — |
| X9 | src/drivers/ios/slim-boot.ts:261 |
labelCount counts every label written true |
counts exclude names with no code change |
B3 |
| X10 | website/src/content/docs/docs/reference/configuration.mdx:206; using-devices/choosing-a-device.mdx:107-118; docs/internal/EVENTS.md:106; src/drivers/ios/AGENTS.md (slim rules, Known gaps) |
categories only | both keys, the precedence, the record, the typo and old-baseline gaps | B5 |
Tasks
- Slim: worker include and exclude lists of single services #1650 Slim: worker include and exclude lists of single services — an operator keeps single services running or turns them off on slim simulators from the worker config. Risk: a service that should run stays off (push, StoreKit,
log stream), or a slim worker grantsfulldevices.
Completion conditions: all five by #1650 (the real-simulator ones through its slow-lane Done when line).
Open work in the same area:
- feat(console): offer proxy SSO sign-in alongside operator tokens #1632 (proxy SSO sign-in) and feat(leasing): a worker serves only enrolled devices on a platform whose virtualDevices is false #1623 (enrolled-only workers) add fields to
src/core/config-types.ts, away fromDriverConfigEntry's newcheck: no Depends on. - fix(ios): the simctl commands of a simulator's lifecycle wait ios.simulator.lifecycleTimeoutMs, and a create or clone that answers late is deleted (#1546) #1547 (lifecycle timeout, draft) adds a key to
ios.simulatorinsrc/drivers/ios/definition.ts, notios.slim: no Depends on. - A worker refuses the iOS modes it does not serve (ios.modes, MODE_UNAVAILABLE) #1651 (
ios.modes, task:draft, feature Restrict iOS lease modes on a worker #1645) adds a worker check in the same post-merge block ofconfigFromLayersand edits the same slim section ofchoosing-a-device.mdxand theios.*rows ofconfiguration.mdx: different lines, no Depends on; the second to land merges. - feat(backends): register local backend modules #1497 (backend modules, draft PR, no task) replaces
DriverConfigEntrywithBackendDefinition: whichever lands second moves I4'scheckonto the other's type; no Depends on, since it has no task.
Written by an agent.
Activity
V3RON commentedon Nov 17, 2026
Design posted: business sections, Decisions (ADR 0082), Behaviours B1–B6, S1, I1–I3, Existing code.
Written by an agent.
docs(adr): 0082 records the named services it wrote (#1644)
docs(adr): accept 0082 (#1644)
V3RON commentedon Nov 17, 2026
Spec updated: task #1650 posted; Tasks section and Task cells filled.
Written by an agent.
docs(adr): renumber to 0083, 0082 is taken by #1647 (#1644)
V3RON commentedon Nov 17, 2026
Spec updated: the ADR is renumbered 0083 (PR #1647 holds 0082); S2's record is written only when it changes; #1651 listed under open work; #1650 names the slim test helper and the write checks it touches.
Written by an agent.
docs(adr): a recorded name in neither list follows §2, not a blanket …
V3RON commentedon Nov 17, 2026
Delivery run
Merged: none
Parked: #1650 — PR #1655 ready and
needs-hardware: the slow lane refused this machine (10.2 GiB free disk, needs 15); the stack #1646 → #1655 waits on itWaiting: none
Decided: none
Written by an agent.