Skip to content

CarPlay on iOS simulators

AutoMobile cannot observe, record or tap the CarPlay screen yet. What works today is reading the templates your app shows on CarPlay, and acting on them, through the AutoMobile iOS SDK in a Debug build. This page covers that path and what is not supported.

What works today

  • iOS simulators only, with a Debug build of your app that includes the AutoMobile SDK.
  • GET /carplay/templates on the SDK’s HTTP server: the template stack your app shows on CarPlay, as JSON.
  • POST /carplay/action: select a list row, image-row element, alert action or tab, go back, or pop to the root template.
  • startDevice with carPlay: {} turns on the CarPlay screen of an iOS 26.x simulator without the Simulator window. See Turn on the CarPlay screen with startDevice.
  • The carPlay device resource setting turns CarPlay vehicle connectivity off on a simulator. See Configuring device resources.

No MCP tool reads the template tree or sends these actions. observe, screenshots and videoRecording capture the phone screen only.

Open the CarPlay window

In Simulator, choose I/O > External Displays > CarPlay. A booted simulator lists the CarPlay screen even while this window is closed, so the listing does not mean the screen is showing. AutoMobile does not open or close the window for you; to turn the screen on without it, use startDevice as below.

Turn on the CarPlay screen with startDevice

An iPhone simulator can show its CarPlay screen with no Simulator.app window. Ask for it with startDevice.

Requirements

  • An iPhone simulator on an iOS 26.x runtime from Xcode 26.x. Apple does not support CarPlay on the iOS 27 Simulator.
  • Two local executables, named by environment variables on the daemon:
  • AUTOMOBILE_CARPLAY_POWER_HELPER_PATH: the carplay-power-helper, which turns on the CarPlay screen.
  • AUTOMOBILE_CARPLAY_PROJECTION_PROBE_PATH: the CarPlay projection probe, which confirms the screen is the car display. Use an absolute path.

Request it

Pass carPlay: {} to startDevice for an iPhone simulator:

{
  "platform": "ios",
  "deviceId": "<simulator UDID>",
  "carPlay": {}
}

Once the simulator is ready and bound to your session, AutoMobile turns on its CarPlay screen and checks that the simulator now reports it as the car display. The response gains a carPlay block:

Field Description
display The car display’s identity, for example Car[2].
displayId The simulator screen id of the car display.

The simulator forgets the CarPlay screen whenever it boots, including after killDevice or when a released device is reset. Pass carPlay: {} on each startDevice call that needs it; asking again on a simulator that already shows CarPlay is harmless.

Errors

Error What to do
carPlay needs an iOS iPhone simulator Use platform: "ios". Android phones use Android Auto.
[unsupported-runtime] Headless CarPlay needs an iOS 26.x runtime ... The simulator runs iOS 27 or later. Create an iOS 26.x simulator with Xcode 26.x and request it there.
A message asking you to set AUTOMOBILE_CARPLAY_POWER_HELPER_PATH or AUTOMOBILE_CARPLAY_PROJECTION_PROBE_PATH Build the executable, set the variable for the daemon, restart the daemon and retry.
... is ready and bound to session ..., but its CarPlay display is not available The simulator stays ready and held by your session. The rest of the message says what failed. Fix it and call startDevice again, or release the device. If the screen is not the car display, reboot the simulator and retry.

Register your CarPlay scene

Call AutoMobileSDK.shared.initialize() early in your app’s launch; it starts the SDK’s HTTP server. Then call registerCarPlay when your CarPlay scene connects, passing the interface controller it receives, and unregisterCarPlay when the scene disconnects:

AutoMobileSDK.shared.registerCarPlay(interfaceController: interfaceController)
AutoMobileSDK.shared.unregisterCarPlay()

Registration does nothing in a Release build. Your app still needs its own CarPlay entitlement and scene configuration; the SDK does not add them. For how the SDK reads the templates, see CarPlay templates and actions.

Read the templates

The SDK serves the routes on port 8766 on the host, as long as no other simulator holds that port. It also listens on a port between 40000 and 40999 chosen from the simulator’s UDID. When several simulators are booted, 8766 may belong to another app: find your app’s port with lsof -nP -iTCP -sTCP:LISTEN and use it in place of 8766.

Set UDID to your simulator’s UDID, from xcrun simctl list devices booted. With the X-AutoMobile-Simulator-UDID header, a different simulator’s app refuses the request with HTTP 409 wrong_simulator. Without the header, the request reaches whichever app holds the port, so stop when UDID is empty:

: "${UDID:?Set UDID to the target simulator UDID}"
curl -s -H "X-AutoMobile-Simulator-UDID: $UDID" http://127.0.0.1:8766/carplay/templates

Both GET /carplay/templates and POST /carplay/action answer while your app is in the background, because CarPlay can stay active then. The simulator identity check still applies to both.

Field Meaning
enabled The app has called registerCarPlay. It stays true after unregistering.
connected The registered controller is still alive.
templates The controller’s stack, bottom to top. Empty before registration.
presented The presented template, such as an alert or action sheet, when one is up.
truncated Some nodes were left out because a size limit was reached.

Each node has an id and a type: list, grid, tabBar, information, alert, actionSheet, pointOfInterest, map, contact, voiceControl, nowPlaying, search or unknown (with className). Lists carry sections and rows with text, detail text, enabled and hasImage; grids carry title variants; tab bars carry the selected tab and each tab’s template. Images are never included. The tree describes the templates your app set, not the pixels CarPlay drew.

A snapshot holds at most 50 items in any collection, 500 nodes and 6 levels. IDs are paths such as stack/0/sections/1/items/0 or stack/0/tabs/1. They name positions in the current snapshot only: after any change to the templates, including reordered rows, an old ID can name a different element. Read a fresh snapshot before each action.

Act on a template

curl -s -X POST -H "X-AutoMobile-Simulator-UDID: $UDID" \
  -d '{"id": "stack/0/sections/0/items/0", "action": "select"}' \
  http://127.0.0.1:8766/carplay/action

action is select (the default), back or popToRoot; only select needs an id. A valid request returns HTTP 200 with status, an optional reason and the full templates snapshot taken after the action. If your app updates its templates later, for example after a network call, read the templates again.

status Meaning What to do
ok The handler ran, the tab was selected, or the stack was popped. Check the returned templates.
not_found No node has that id in the current templates, or the node is past a size limit. Read the templates again and use a fresh id. If truncated is true, the element may be out of reach.
failed The element is disabled, a list row has no handler, or the pop failed. Enable the element or add a handler.
unsupported The app has not registered, the controller is gone, or the node has no public selection API. See reason.

Grid buttons, bar buttons and text buttons return unsupported: CarPlay gives no public way to trigger their handlers from outside. Malformed JSON, an unknown action, or select without an id returns HTTP 400 bad_request.

Not supported

Not supported Why
CarPlay screenshots, observe and videoRecording No capture surface is available yet; CarPlay screen captures time out or come back black.
CarPlay in the device list Device listings do not report a CarPlay screen yet.
Tapping, swiping or typing on the CarPlay screen Interaction tools drive the phone screen only. Use POST /carplay/action for template actions.
Physical iPhones, cars and head units Only simulators are supported.
Apple’s CarPlay Simulator app AutoMobile does not connect to it. Use the CarPlay window in Simulator.
CarPlay prototypes Prototypes draw only on the phone screen. See CarPlay prototypes.
Release builds The SDK routes and registration exist only in Debug builds.