400 and code: "invalid_simulator_options",
and field names the field at fault, so a typo never quietly gives you a simulator
without the feature. The SDK and CLI check the same values before they send anything.
What the session reports
A created iOS session includes:Runtime and device
platformVersion takes one value today, and deviceName takes two:
If you leave them out, you get iOS 26.5 on an iPhone 17e. Anything else, such as
"27.0" or
"iPhone 12", is rejected with the list of values that are available. Both fields are
typed lists (IosPlatformVersion, IosDeviceName in @run-cloud/sdk).
"iPad (A16)" is the 11-inch iPad. model: "ipad" without a deviceName gives the same
device. If the iPad is not available to your organization, a named "iPad (A16)" is
rejected with invalid_simulator_options, and model: "ipad" gives the default device.
How capabilities relate to Apple entitlements
Capability names follow Xcode’s Signing & Capabilities tab where one matches. Some of them are not entitlements at all, so the mapping is not one to one. Apple’s reference for entitlements: Entitlements. Some capabilities are detected from your app. iOS refuses an app that uses HealthKit, HomeKit or widgets without declaring it in its bundle, and Apple Account features leave an entitlement or a linked framework behind, so when you install such an app, run.cloud reads the bundle and turns the services on by itself. The others are request-only: an app can reach them through a public API without declaring anything, for example the contact picker or the add-event sheet. Nothing in the bundle shows the need, so you have to ask for them.
Requesting a capability that is also detected is fine: the request just turns it on
before your app is installed rather than after.
Speed and cost
A capability can be on before you claim the simulator, or turned on at claim time.- Standby (fast). run.cloud keeps a few clean simulators with popular capabilities
already on, spread across hosts. If one matches your request, you get it with no extra
wait (
capabilities.standbylists what it already had). - Cold (slower). Otherwise you get a plain simulator, and the services start inside it before the create call returns. Nothing reboots. Measured: the 14 Health, HomeKit and widget services came up in 12.2 s, so about 12 s for the 12 Health and HomeKit services. The per-capability figures below are estimates at a little under 1 s per service.
Capabilities
HealthKit
Enables: reading and writing Health data (HKHealthStore), workouts, Activity rings
and Fitness data.
iOS services: healthd, healthappd, healthcontentd, healtheventsd,
healthrecordsd, fitcore, fitcore.session, fitnesscoachingd, activityawardsd,
activitysharingd.
Apple: the HealthKit capability in Xcode adds the
com.apple.developer.healthkit
entitlement. Any NSHealth*UsageDescription key in the app or one of its extensions
switches this capability on at install.
Detected: yes. Cold latency: about 9 s (about 12 s together with HomeKit).
Memory: not measured on its own yet. Together with HomeKit, the services stay mostly idle until your app uses them.
HomeKit
Enables:HMHomeManager: homes, rooms, accessories and automations.
iOS services: homed, homeeventsd.
Apple: the HomeKit capability adds
com.apple.developer.homekit.
NSHomeKitUsageDescription switches it on at install.
Detected: yes. Cold latency: about 2 s (about 12 s together with HealthKit).
Memory: not measured on its own; measured together with HealthKit.
WidgetKit
Enables: Home Screen and Lock Screen widgets, their timeline refreshes, Live Activities and the Dynamic Island. iOS services:chronod (widget refresh), liveactivitiesd (Live Activities).
Wallpapers (PosterBoard) stay off: no app can set one.
Apple: there is no widget entitlement. Xcode adds a Widget Extension target whose
NSExtensionPointIdentifier is com.apple.widgetkit-extension. Live Activities need
NSSupportsLiveActivities = YES in the app’s Info.plist. We use the framework name
WidgetKit rather than “Widgets” or “LiveActivities” because one switch covers both, and
it matches the name Apple uses for the framework.
Detected: yes. Cold latency: about 2 s. Memory: the largest of the set,
about +0.85 GB per simulator measured with a widget app. Turning widgets back on also
restarts Apple’s own widgets. Four simulators running a widget app took 7.6 GB, against
4.5 GB for a plain app.
SpeechSynthesis
Enables: text to speech throughAVSpeechSynthesizer, and so expo-speech and
React Native TTS libraries. Without it, speak() returns and nothing is heard.
iOS services: sirittsd, voiced, mobileassetd.
Apple: no entitlement or usage key. The API is public and needs no declaration,
which is also why it cannot be detected.
Detected: no, request it. Cold latency: about 3 s. The first utterance may take
longer while the voice asset loads. Memory: not measured yet. mobileassetd also
serves other on-demand system assets.
Contacts
Enables: the Contacts database (CNContactStore) and the contact picker
(CNContactPickerViewController).
iOS services: contactsd, contacts.postersyncd.
Apple: the picker needs nothing. Reading contacts directly needs
NSContactsUsageDescription and the user’s permission. There is no entitlement unless you
use the managed com.apple.developer.contacts.notes field.
Detected: no, request it. Cold latency: about 2 s. Memory: not measured on its own.
Calendars
Enables: EventKit events and reminders (EKEventStore), and the add-event sheet
(EKEventEditViewController).
iOS services: calaccessd (events), remindd (reminders).
Apple: since iOS 17 the add-event sheet needs no permission. Direct access needs
NSCalendarsFullAccessUsageDescription or NSRemindersFullAccessUsageDescription. No
entitlement.
Detected: no, request it. Cold latency: about 2 s. Memory: not measured on its own.
AppleAccount
Enables: signing in to an Apple Account in the simulator: Sign in with Apple, Game Center, and Settings > Developer > Sandbox Apple Account for testing StoreKit and RevenueCat in-app purchases. iOS services:akd, appleaccountd, appleaccounttransparencyd, appleidsetupd,
cdpd, ap.adprivacyd, followupd, askpermissiond, familycircled. The StoreKit
services (storekitd, itunesstored, amsaccountsd, accountsd, appstored) are
always on.
Apple: Sign in with Apple and Game Center have entitlements. In-App Purchase has
none, so run.cloud also looks for an embedded RevenueCat framework or a binary that links
StoreKit. An app whose purchases SDK is linked statically and that never links StoreKit
itself is not detected: request AppleAccount.
Detected: yes. Cold latency: not measured; estimated a few seconds for nine
services. Memory: not measured.
Some of these services may already be running in your simulator. Ask for every
capability your app needs anyway: run.cloud can switch unused services off at any time,
and sessions that ask keep working unchanged.