> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.doc-detective.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server.

# Device descriptor

> Reference for the `Device descriptor` schema.

## Referenced In

* [context](/reference/schemas/context)
* [App descriptor](/reference/schemas/app-descriptor)

## Fields

| Field       | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                 | Default |
| :---------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |
| platform    | string  | Optional. Target platform. Selects the mobile driver. Required in `startSurface.device`; implied by the context in `context.device`. Accepted values: `android`, `ios`                                                                                                                                                                                                                                                                      | —       |
| name        | string  | Optional. Device name and registry identity — the same name resolves to the same device. Reference form: names an existing AVD (Android) / simulator (iOS) to reuse. If no device by this name exists, Doc Detective creates one under this name using `deviceType`/`osVersion` (or their defaults), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Minimum length: 1. Pattern: `\S` | —       |
| deviceType  | string  | Optional. Abstract hardware profile used when creating a device (portable across `android`/`ios`). Doc Detective maps it to a built-in profile. Ignored when `name` already matches an existing device. Default: `phone`. Accepted values: `phone`, `tablet`                                                                                                                                                                                | —       |
| osVersion   | string  | Optional. Platform version used when creating a device; must match an installed image/runtime for the target platform (install more with `doc-detective install android` or `doc-detective install ios`). Ignored when `name` already matches an existing device. Default: the newest installed version. Minimum length: 1                                                                                                                  | —       |
| headless    | boolean | Optional. Run the Android emulator without a window. No-op on iOS (simulators boot without the Simulator UI on CI) and ignored where not applicable.                                                                                                                                                                                                                                                                                        | —       |
| orientation | string  | Optional. Initial orientation. Reserved; validated now, not yet implemented. Accepted values: `portrait`, `landscape`                                                                                                                                                                                                                                                                                                                       | —       |
| udid        | string  | Optional. Pin a specific device/emulator instance by UDID. Reserved; validated now, not yet implemented. Minimum length: 1                                                                                                                                                                                                                                                                                                                  | —       |
| provider    | object  | Optional. Cloud device farm configuration, keyed by provider. Reserved; validated now, not yet implemented.                                                                                                                                                                                                                                                                                                                                 | —       |

## Examples

```json
{
  "platform": "android",
  "name": "example",
  "deviceType": "phone",
  "osVersion": "example",
  "headless": true,
  "orientation": "portrait",
  "udid": "example",
  "provider": {}
}
```