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

# startSurface

> Reference for the `startSurface` schema.

## Referenced In

* [Markup definition](/reference/schemas/markup-definition)
* [test](/reference/schemas/test)
* [Resolved context](/reference/schemas/resolved-context)

## Fields

| Field        | Type                                                                                                                                                                                                                                                                                                                                                                                                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Default |
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------ |
| startSurface | one of: - object([App descriptor](/reference/schemas/app-descriptor)) - object([Browser descriptor](/reference/schemas/browser-descriptor)) - object([Process descriptor](/reference/schemas/process-descriptor)) - array of one of: object([App descriptor](/reference/schemas/app-descriptor)), object([Browser descriptor](/reference/schemas/browser-descriptor)), object([Process descriptor](/reference/schemas/process-descriptor)) | Required. Open (provision) one or more surfaces and register them by name so later steps can target them with `surface`. Three kinds: a native APP (Windows/macOS desktop by executable path, `.app` path, bundle ID, or UWP AppUserModelID; Android/iOS apps on managed emulators/simulators — macOS desktop additionally requires the Accessibility permission for the process that runs Doc Detective), a BROWSER session (opens blank and ready on the context's automation server; navigate it with a `goTo` step), or a background PROCESS (equivalent to `runShell` with `background` — both forms stay valid). An ARRAY of descriptors opens them all concurrently — the step completes when every one is ready, and device boots overlap. See docs/design/multi-surface-targeting.md and docs/design/native-app-surfaces.md. | —       |

## Examples

```json
{
  "startSurface": {
    "app": "C:\\Windows\\System32\\notepad.exe"
  }
}
```

```json
{
  "startSurface": {
    "app": "Microsoft.WindowsCalculator_8wekyb3d8bbwe!App",
    "name": "calc"
  }
}
```

```json
{
  "startSurface": {
    "app": "/Applications/Calculator.app",
    "name": "calc",
    "args": [
      "--reset"
    ],
    "waitUntil": {
      "delayMs": 500
    },
    "timeout": 30000
  }
}
```

```json
{
  "startSurface": {
    "app": "com.example.myapp",
    "install": "./build/MyApp.apk",
    "device": {
      "platform": "android",
      "name": "Pixel_7"
    }
  }
}
```

```json
{
  "startSurface": {
    "browser": "firefox",
    "name": "admin",
    "headless": true,
    "size": {
      "width": 1366,
      "height": 768
    }
  }
}
```

```json
{
  "startSurface": {
    "process": "node server.js",
    "name": "api",
    "waitUntil": {
      "httpGet": "http://localhost:8080"
    },
    "timeout": 30000
  }
}
```

```json
{
  "startSurface": [
    {
      "browser": "chrome",
      "name": "web"
    },
    {
      "process": "node server.js",
      "name": "api",
      "waitUntil": {
        "port": 8080
      }
    }
  ]
}
```

```json
{
  "startSurface": [
    {
      "app": "com.example.chat",
      "name": "alice",
      "device": {
        "platform": "android",
        "name": "Pixel_7"
      }
    },
    {
      "app": "com.example.chat",
      "name": "bob",
      "device": {
        "platform": "android",
        "name": "Pixel_7_second"
      }
    }
  ]
}
```