WebDriverAgent

WebDriverAgent — WDA — is a small app the Companion installs onto each iPhone. It is what actually taps the screen. Without it a phone is visible but inert: no streaming, no remote control, no automations. Every iPhone needs its own copy, and iOS will not run an app that has not been signed by an Apple developer account. The Companion handles the signing and the install for you. You never open Xcode.

​

Build, Start and Stop

Three buttons, and the difference matters. This is how the Companion itself puts it:

• Build — install WebDriverAgent onto the phone. You do this once per phone, or after an iOS update.
• Start — launch WDA so the phone goes online and streamable. You do this each session.
• Stop — take the phone offline without removing WDA.
• If a phone misbehaves, Stop → Build → Start gives it a fresh WDA.

The buttons read Build WDA, Start WDA and Stop WDA in the device panel, and a slow start can be abandoned with Cancel Start. The Bulk actions menu on the Devices screen has Build All, Start All and Stop All; Build All deliberately skips phones that already have WDA, so it will not re-sign your whole fleet by accident.

​

How long each step takes

Build walks through five stages, and the Companion names each one as it goes: Budget about five minutes for a first build. Start is quicker: the Companion launches WDA and waits up to 90 seconds for it to answer. If it does not answer in that time, the developer app almost certainly has not been trusted on the phone yet — see Connect your phones. Once a phone is running, the Companion checks its health every 30 seconds. Two failures in a row and it restarts WDA on its own, up to three times, and then rebuilds. You do not have to watch for this; it is why a phone sometimes goes Starting again without you touching anything.

​

The two ways WDA gets signed

Pick one. Server signing is the recommended default and is set up once for the whole organization; Apple ID signing is set up on each Mac by whoever runs it.

​

Server signing

The dashboard signs WDA for you, so nothing about signing has to exist on the Macs your operators use. Set it up in Settings → WDA Signing — “Sign WebDriverAgent on our servers or locally in the Companion”. The section is only visible to people whose role includes Manage integrations. Each account row shows Devices registered this year as a count out of 100, along with the key ID, the certificate expiry and the header Total capacity across every account you have connected. A newly registered phone sometimes has to wait on Apple’s side. That reads “Apple is still verifying this device — this typically resolves overnight. Try building again in a few hours.” Nothing is broken; try again later.

​

Apple ID signing

The Companion signs WDA on the Mac itself, using an Apple ID you sign in with. Any Apple ID works, including a free one — no paid Developer Program membership and no App Store Connect key. You never type a team ID or a bundle identifier. Both are worked out from the Apple ID. This setting is per Mac. A second Mac running the Companion has its own signing method and its own Apple ID.

​

The statuses you will see

While the agent is coming up or going down, the dashboard shows one pill and the Companion shows another. They line up like this: The dashboard’s device panel also shows a small agent chip carrying the current phase — “build 40%”, “starting”, “ready”, “error” — and a Last message row with the Companion’s own wording. That message is the useful one when a build stalls. If you do not have the Remote control devices permission, the chip reads “permission required” and the buttons do nothing: “Remote control devices permission is required to manage the agent.”

​

When Build or Start fails

Anything not in this list still lands in Sprout, the Companion’s assistant panel. When it has no specific fix it shows the raw message under “Something went wrong” — copy that text and send it to support.

​

What to read next