> 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.

# App descriptor

> Reference for the `App descriptor` schema.

## Referenced In

* [startSurface](/reference/schemas/startsurface)

## Fields

| Field            | Type                                                                                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Default |
| :--------------- | :----------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| app              | string                                                                               | Required. The app identifier: an executable path (`C:\\Windows\\System32\\notepad.exe`), a `.app` path, a bundle ID (`com.apple.TextEdit`), a package name (`com.example.myapp`), or a UWP AppUserModelID (`Microsoft.WindowsCalculator_8wekyb3d8bbwe!App`). Disambiguated by syntax — never by a type field. Minimum length: 1. Pattern: `\S`                                                                                                                                                               | —       |
| name             | string                                                                               | Optional. Surface-registry name later steps use in `surface`. Default: the executable basename without extension, or the final dot-segment of an ID. Minimum length: 1. Pattern: `\S`                                                                                                                                                                                                                                                                                                                        | —       |
| args             | array of string                                                                      | Optional. Launch arguments (desktop apps). On macOS they pass to the app as a real argument array. On Windows they join into a single shell-style argument string for the driver, so an argument with embedded spaces must carry its own quotes (e.g. ""My File.txt"").                                                                                                                                                                                                                                      | —       |
| workingDirectory | string                                                                               | Optional. Working directory for the launched app. Not honored by the current desktop app drivers, so a non-default value fails with guidance: on Windows the NovaWindows driver ignores it (the app inherits the driver's own working directory), and on macOS the driver launches apps through LaunchServices, which offers no working-directory control. Launch the app via runShell if the cwd matters. Reserved for when a driver gains support. Default: the run's working directory. Minimum length: 1 | `.`     |
| env              | object                                                                               | Optional. Extra environment variables for the launched app (desktop apps). Supported on macOS; not supported by the Windows driver, where any value fails with guidance (set variables in the shell that launches Doc Detective instead).                                                                                                                                                                                                                                                                    | —       |
| install          | string                                                                               | Optional. Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces. Minimum length: 1                                                                                                                                                                                                                                                                                                                                        | —       |
| activity         | string                                                                               | Optional. Android main activity override (defaults to the package's launcher activity). Android-only. Minimum length: 1                                                                                                                                                                                                                                                                                                                                                                                      | —       |
| device           | one of: - string - object([Device descriptor](/reference/schemas/device-descriptor)) | Optional. Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context's default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.                                                                                                                                                                                                                                                                        | —       |
| driverOptions    | object                                                                               | Optional. Escape-hatch passthrough: merged into the automation session's capabilities after the ones Doc Detective computes (namespaced per driver, e.g. `appium:noReset`). Driver- and version-specific; use sparingly.                                                                                                                                                                                                                                                                                     | —       |
| waitUntil        | object([App readiness](/reference/schemas/app-readiness))                            | Optional. Startup readiness: a fixed delay and/or an element that must exist before the surface is considered open. No condition applies by default.                                                                                                                                                                                                                                                                                                                                                         | —       |
| timeout          | integer                                                                              | Optional. Startup ceiling in milliseconds (launch + install + readiness). Minimum: 0                                                                                                                                                                                                                                                                                                                                                                                                                         | `60000` |

## Examples

```json
{
  "app": "example",
  "name": "example",
  "args": [],
  "workingDirectory": ".",
  "env": {},
  "install": "example",
  "activity": "example",
  "device": "example",
  "driverOptions": {},
  "waitUntil": {
    "delayMs": 42
  },
  "timeout": 60000
}
```