Skip to main content
A phone joins your fleet by being plugged into a Mac that is running the Companion. There is no pairing code and no app to install on the phone. This page covers iPhones; GrapheneOS phones are on Android phones.

​
What you need

  • A good Apple cable, plugged into a port on the Mac itself. Hubs and cheap cables are the single most common cause of a phone that never appears.
  • The phone unlocked, with the screen on.
  • The Companion open and signed in.

​
Plug it in

1

Connect the phone to the Mac by USB

The Companion scans for phones every few seconds, so a new one shows up within about three seconds rather than instantly.
2

Unlock the phone and tap Trust

The iPhone asks “Trust This Computer?”. Tap Trust and enter the passcode. Until you do, the row reads Tap Trust on iPhone and no buttons work.
3

Turn on Developer Mode

On the phone: Settings → Privacy & Security → Developer Mode, switch it on. The phone restarts and asks you to confirm with Turn On after it comes back. This is needed once per iPhone.
4

Press Build, then Start

Build installs the automation agent onto the phone and takes a few minutes. Start brings it online. See WebDriverAgent for what these do and what can go wrong.
The Companion Devices screen showing a table with Device, Status, OS, UDID, Port and Actions columns, one row with a Ready status pill and one with a Running status pill, and Build, Start and Stop buttons in the Actions column

The Companion's Devices list with two iPhones connected.

The dashboard has a Pair a new phone wizard on the Fleet page that walks the same ground and shows a green Detected card the moment the phone registers.

​
The two Trust steps are different

Almost everyone hits this once. There are two separate approvals on the phone and they happen at different moments. Miss the second one and Start fails after 90 seconds with “WDA did not become ready within 90s. This usually means the developer app isn’t trusted yet…”. Trust it, then press Start again.
You never have to press anything to retry the first Trust. The Companion keeps asking the phone every few seconds and lights the row up on its own the moment you tap Trust.

​
What you see in the Companion

The Devices screen lists every phone the Mac can see, with columns for Device, Status, OS, UDID, Port and Actions. With nothing plugged in it reads “No Devices Connected” — “Connect an iOS device via USB to get started. Make sure the device is unlocked and you’ve trusted this computer.” The status pill is the thing to read: A phone that briefly drops off is not shown as offline straight away — it has to be missed three scans in a row, so a jiggled cable does not make the list flicker. An iPhone that has been connected to this Mac before comes back as Ready and does not need rebuilding. A phone the Mac has never seen comes back as Detected.

​
Which iPhones work

There is no minimum iOS version. The Companion builds a different variant of the agent depending on the version, covering iOS 15 and 16, iOS 17 through 25, and iOS 26 and newer. The practical differences:
  • iOS 17 and newer need a secure tunnel, which is why macOS asks for your login password once per session. Approve it.
  • iOS 15 and 16 never trigger that prompt.
  • iOS 16 and newer need Developer Mode turned on, as above.
Phone models from the iPhone 13 through the iPhone 16 Plus are shown by name. Anything outside that range shows its raw Apple product code, something like iPhone17,1. That is cosmetic — the phone works the same.

​
If the phone does not appear

Keep the phone awake while it works. A locked screen stops a run and produces “iPhone is locked. Please unlock your iPhone and try again.” Phones in a fleet are normally left plugged in with auto-lock turned off.

WebDriverAgent

What Build and Start actually do, and every error they can throw.

Your fleet

The phone on the dashboard side, and what its statuses mean there.