> ## Documentation Index
> Fetch the complete documentation index at: https://docs.run.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS Simulator Capabilities

> Turn on HealthKit, HomeKit, widgets, speech, contacts, calendars or Apple Account sign-in in a remote iOS simulator, and pick its runtime and device.

run.cloud simulators run a slimmed iOS. Services most apps never touch are switched
off, so each simulator uses less memory and starts sooner. If your app needs one of
those services, ask for the **capability** that turns it back on.

You ask for capabilities the same way WebDriver and Appium clients describe a device:

```json theme={null}
{
  "platformName": "iOS",
  "runcloud:options": {
    "capabilities": ["HealthKit"],
    "platformVersion": "26.5",
    "deviceName": "iPhone 17e"
  }
}
```

```bash Bash theme={null}
runcloud ios create --capability HealthKit --capability WidgetKit --json
```

```typescript TypeScript theme={null}
import { Client } from "@run-cloud/sdk";

const cloud = new Client();
const session = await cloud.ios.create({
  platformName: "iOS",
  "runcloud:options": { capabilities: ["HealthKit", "WidgetKit"] },
});
console.log(session.capabilities);
// { requested: ["HealthKit", "WidgetKit"], enabled: ["HealthKit", "WidgetKit"], failed: [], standby: ["HealthKit"] }
```

```bash curl theme={null}
curl -X POST "$RUN_CLOUD_API_URL/run-cloud/ios" \
  -H "Authorization: Bearer $RUN_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platformName":"iOS","runcloud:options":{"capabilities":["HealthKit"]}}'
```

Every field is optional. When a field is present, its value must be one that run.cloud
supports. Otherwise the request fails with `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:

| Field | Meaning |
| - | - |
| `platformVersion` | The iOS runtime, e.g. `"26.5"`. |
| `deviceName` | The simulator device type, e.g. `"iPhone 17e"`. |
| `capabilities.requested` | What you asked for. |
| `capabilities.enabled` | What is running now. |
| `capabilities.failed` | What was asked for but did not start. The session still works, just without that feature. Release it and retry if you need the feature. |
| `capabilities.standby` | What was already on when you got the simulator, so there was no wait. |

## Runtime and device

`platformVersion` takes one value today, and `deviceName` takes two:

| Field | Accepted values |
| - | - |
| `platformVersion` | `"26.5"` (iOS 26.5) |
| `deviceName` | `"iPhone 17e"` (the default), `"iPad (A16)"` |

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](https://developer.apple.com/documentation/bundleresources/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.

| Capability | Apple entitlement or key | Detected from the bundle? |
| - | - | - |
| `HealthKit` | [`com.apple.developer.healthkit`](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.healthkit) entitlement, plus the `NSHealthShareUsageDescription` / `NSHealthUpdateUsageDescription` usage keys | Yes: any Health usage key in the app or an extension |
| `HomeKit` | [`com.apple.developer.homekit`](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.homekit) entitlement, plus `NSHomeKitUsageDescription` | Yes: the HomeKit usage key |
| `WidgetKit` | No entitlement. A Widget Extension target (`com.apple.widgetkit-extension`) or `NSSupportsLiveActivities` in `Info.plist` | Yes: a widget extension or Live Activities |
| `SpeechSynthesis` | None. `AVSpeechSynthesizer` needs no declaration | No: request it |
| `Contacts` | None required for the contact picker. Direct access uses `NSContactsUsageDescription` | No: request it |
| `Calendars` | None required for the add-event sheet. Direct access uses `NSCalendarsFullAccessUsageDescription` / `NSRemindersFullAccessUsageDescription` | No: request it |
| `AppleAccount` | `com.apple.developer.applesignin`, `com.apple.developer.game-center` or `com.apple.developer.in-app-payments`; In-App Purchase needs none | Yes: one of those entitlements, an embedded `RevenueCat`, `RevenueCatUI` or `PurchasesHybridCommon` framework, or a binary linking `StoreKit` |

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.standby` lists 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.

The memory figures below are measured on run.cloud simulators (iPhone 17e, iOS 26.5). Capabilities cost nothing until you ask for one, which is why they are off by default.

## 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`](https://developer.apple.com/documentation/bundleresources/entitlements/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`](https://developer.apple.com/documentation/bundleresources/entitlements/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 through `AVSpeechSynthesizer`, 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.

> [!NOTE]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.