> ## Documentation Index
> Fetch the complete documentation index at: https://ai-development-environment.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulators

> Create, start, and manage Xcode simulators on your Mac agents.

![Simulator inventory in light theme](https://mintcdn.com/ai-development-environment/pLiqH4xc0vSw3uYP/images/light/simulators.png?fit=max\&auto=format\&n=pLiqH4xc0vSw3uYP\&q=85\&s=c19cda6a8c461973109a87e75748a469)

Open **System → Simulators** at `/system/simulators` or in the iOS and tvOS apps. The list groups devices by agent and shows each simulator's model, runtime, and state. Search the list or filter it by platform and state.

Choose an agent to see its devices, or choose **All Agents** to see the fleet. The global active agent takes precedence while set. When you clear it, the page restores its saved agent filter.

## Create or start a simulator

1. Choose **Create Simulator** and select the target Mac agent.
2. Choose one of its installed runtimes and a compatible device model, then enter a name.
3. Use **Start** or **Shut Down** from the list. Select the simulator name to open its [details](https://ai-development-environment.mintlify.site/system/simulator-detail.md).

An agent needs Xcode and simulator management support. If the agent is offline, reconnect it before refreshing its inventory or sending an action.

## Delete multiple simulators

![Simulator Edit mode with two devices selected in light theme](https://mintcdn.com/ai-development-environment/pLiqH4xc0vSw3uYP/images/light/simulators-edit.png?fit=max\&auto=format\&n=pLiqH4xc0vSw3uYP\&q=85\&s=047f62c7158e9a818559c1af02b925d4)

1. Choose **Edit** to show selection controls.
2. Select individual simulators, or use the checkbox in an agent's group to select every visible simulator on that Mac that can be deleted. You can select shut-down devices and unavailable devices stuck in **Creating**. Set your filters before selecting devices.
3. Choose **Delete selected**, review the device count, and confirm. This removes the selected devices and their data.

The list refreshes after deletion. If a device could not be deleted, review the error before retrying. Choose **Done** to leave Edit mode.

## Reset to default simulators

Choose **Reset to Default Simulators** for the Mac whose roster you want to replace. Shut down its simulators before confirming. The agent validates the default roster for its installed runtimes, creates the replacements, and removes the original devices.

> [!WARNING]
>
> Reset removes custom devices and their data, including installed apps and settings. The replacements have new simulator UUIDs. Pairings attached to the removed devices are lost.

If part of the reset fails, read the error and check the refreshed list before retrying. To clear one simulator's apps and settings while keeping its UUID, use **Erase Contents and Settings** on its detail page.

## Automate simulators with MCP

![Simulator MCP tools in light theme](https://mintcdn.com/ai-development-environment/pLiqH4xc0vSw3uYP/images/light/tools-simulators.png?fit=max\&auto=format\&n=pLiqH4xc0vSw3uYP\&q=85\&s=5aae0dcce8293f8e686f7085af94caeb)

Open the **Simulators** group in [Tools](https://ai-development-environment.mintlify.site/system/tools.md) or discover it in your MCP client. Use `agentId` to choose the Mac. Use the simulator UUID as `simulatorId` for device and app operations, and use `bundleId` for app operations. Creation uses `name`, `runtimeId`, and `deviceTypeId` from the target agent's inventory.

| Permission | Tools |
| - | - |
| Read | `refresh_simulator_inventory`, `inspect_simulator`, `get_simulator_job` |
| Write | `create_simulator`, `rename_simulator`, `clone_simulator`, `open_simulator_data_folder`, `reveal_simulator_app_bundle`, `open_simulator_app_data_folder` |
| Destructive | `boot_simulator`, `shutdown_simulator`, `reboot_simulator`, `erase_simulator`, `delete_simulators`, `reset_simulators`, `launch_simulator_app`, `terminate_simulator_app` |

1. Queue `refresh_simulator_inventory` with the target `agentId` and a `requestId` you generate. The response gives you a `jobId`.
2. Poll `get_simulator_job` with the same `agentId` and the returned `jobId`. `QUEUED`, `RUNNING`, and `CANCELLING` mean the operation is still in progress. On `SUCCEEDED`, read `job.inventory` for devices, runtimes, and compatible device types. On failure, review `job.error`.
3. Queue `inspect_simulator` with the agent, a simulator UUID from inventory, and a new `requestId`. Poll its job and read `job.details` for the simulator and its installed apps. Boot the simulator to load the full app list.

Create and clone jobs return the resulting device UUID in `job.simulatorId`. Inspection can include paths on the owning Mac. Finder tools open those locations on that Mac.

Keep `requestId` stable when retrying the same submission. Choose a new ID when changing the operation or its inputs. Erase, delete, and reset require `confirm: true`. `delete_simulators` accepts 1 to 200 `{ agentId, simulatorId }` pairs in `targets` and returns a job or queue error for each target. Poll each accepted job to confirm deletion. A run-scoped tool call can target only the run's own agent, including every target in a bulk deletion.

To wait for simulator work and pass its results to subsequent actions, use [simulator workflow steps](https://ai-development-environment.mintlify.site/workflows/workflow-edit.md#automating-simulators).


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