The Device Control Protocol (DCP) is one protocol for three kinds of session: browsers, phones and computers (a whole Windows desktop). A session’s control_url is a WebSocket that carries it; inside a Halyard sandbox, a phone also answers it on a local socket. The Python driver speaks it for you (browser, phone, computer), but the connection is yours: open it directly to drive a session from any language.

How the wire looks

DCP is framed like the Chrome DevTools Protocol: each frame is one JSON object, with no envelope around it. A command:
{ "id": 1, "method": "Page.navigate", "params": { "url": "https://example.com" } }
The response echoes the id:
{ "id": 1, "result": { "url": "https://example.com/", "status": 200, "navigationId": "7c1e...", "navigated": true }, "seq": 12 }
A method name is Domain.method. Commands on one connection run one at a time, in the order sent. Timestamps are epoch milliseconds.
FieldOnMeaning
idcommand, responseAn integer you choose, unique on the connection; the response echoes it.
methodcommandDomain.method, such as Locator.click.
paramscommandThe method’s arguments. Omit or send {} when it takes none.
targetIdcommandThe tab a target-scoped method acts on. Omit for the session’s current tab.
frameIdcommandThe frame a frame-scoped method (Locator, DOM, CSS, Page.evaluate, Page.waitForFunction) acts in, from Frame.getFrames. Omit for the tab’s main frame. Cross-origin frames work too.
resultresponseThe result on success, at least {}.
errorresponse{ code, message, data: { kind, retryable, reason? } } on failure. See Error kinds.
seqresponseThe session event log’s position before the command acted. See Event log.

Two tiers of methods

  • The action tier does the work a person would: Locator.click finds an element, waits until it is visible, stable and enabled, scrolls it into view and clicks it with real input, all in one round trip. Your client never polls.
  • The raw tier is input at a point and reads of the screen: Pointer.click on a browser, Touch.tap and Touch.swipe on a phone, Keyboard.typeText, Screen.screenshot, and on a phone Screen.observe, which returns every text region OCR found and every icon on screen.
A phone answers Locator.tap where a browser answers Locator.click: a phone taps.

What each session serves

DomainWhat it doesBrowserPhoneComputer
ProtocolThe handshake: protocol version and the exact methods served.YesYesYes
DeviceWhat the session runs on.YesYesYes
ScreenScreenshots; on a phone, also what is on screen.YesYesScreenshots
KeyboardTyping and key presses at the focus.YesYesYes
PointerMouse input at a point.YesYes
LocatorFind a target, wait for it, then read it or act on it.YesYes, a subsetYes: native apps, and its browser’s pages
BrowserBrowser version and window size.YesOn its browser
TargetTabs: list, open, close, switch, wait for one.YesOn its browser
PageNavigation, page info, scripts, content and the aria snapshot.YesOn its browser
StorageCookies.YesOn its browser
TouchTap, long press and swipe at a point.Yes
AccessibilityThe accessibility tree of a phone, or of a computer’s native apps.While the phone has a treegetFullAXTree and queryAXTree
DisplayThe desktop’s resolution.Yes
WindowTop-level windows.Yes
ProcessCommands and programs.Yes
FileFiles.Yes
ClipboardClipboard text.Yes
Each method page shows a Browser, a Phone and a Computer badge. A method a session doesn’t serve answers StrategyUnavailable. The Frame, DOM, CSS and Network domains are a browser’s, served on a browser session and on a computer’s browser. Read the handshake’s capabilities for the exact set: a phone lists the Accessibility methods only while it has an accessibility tree to serve.

Coordinates

On a browser, points and boxes default to window pixels: Chrome’s whole window as the live view shows it, from its top-left. Pass "space": "viewport" on Pointer.*, Locator.boundingBox and Screen.screenshot to use the page’s CSS pixels from the viewport’s top-left instead, as Playwright does. A point outside the window answers InvalidArgs. On a computer, everything is screen pixels: the desktop’s own, from its top-left ("space": "screen", the only space and the default there). It covers the whole desktop, the taskbar included, and window bounds use it too. On a phone, everything is screen pixels: the phone’s frame from its top-left, at the size Device.info reports (screenWidth, screenHeight). Touch.* points, Screen.observe boxes, Locator result bounds and accessibility node bounds all use it.

How a computer differs

A computer session drives a whole Windows desktop rather than one browser:
  • The whole desktop. The taskbar, every window and every program are there; Screen.screenshot and the live view show all of it, the mouse cursor included.
  • Every chord reaches Windows. The input safety a browser applies (refusing the Windows key, Alt+Tab, Alt+F4 and the rest) doesn’t apply: a computer is yours to drive.
  • Typing. Characters a US keyboard has are pressed as keys; the rest are pasted through the clipboard, which is put back afterwards.
  • The operating system. Display, Window, Process, File and Clipboard reach past the screen. Commands run as the session’s user, who has administrator rights: the machine is the customer’s alone and is reset after the session. C:\ax holds the session’s own software and is read-only except C:\ax\downloads; Windows’ own processes and the session’s agent and streamer can’t be ended.
Browser and phone sessions answer the computer methods with StrategyUnavailable.

The browser on a computer

A computer also serves every browser method, on a Chrome on its own desktop: the computer is the base and the browser sits on top of it, so one session can read a website and work with the desktop’s apps and files. Chrome opens on the first browser call (one already open is used) and again after it closes. The SDK reaches it as computer.browser, a Browser like a browser session’s. Screen, Pointer, Keyboard and Locator are in both. A call that names a page’s targetId acts in that page, in its coordinates. One without acts on the desktop, in screen pixels. So a Locator call with no targetId resolves on the desktop’s UI Automation tree: the native apps’ windows, buttons and fields. The Locator methods only a page has (Locator.evaluate, Locator.blur, Locator.dragTo, Locator.dispatchEvent, Locator.setInputFiles) always go to the browser, to its current tab when no targetId is named. Locator.innerHTML needs a page’s targetId; without one the desktop answers StrategyUnavailable. Accessibility.getFullAXTree and Accessibility.queryAXTree read the same UI Automation tree. Roles there are UI Automation control types (windows.button, windows.edit), and each node carries its bounds in screen pixels. Before the browser’s input acts, Chrome’s window goes back where the browser methods put it and comes to the front, so another window never catches a click meant for the page.

Timeouts

Kind of callFieldDefaultMost
Locator actions and reads (both)timeoutMs5,00060,000
Navigation and page waits (browser)timeoutMs30,000120,000
Window.waitFor (computer)timeoutMs5,00060,000
Process.run (computer)timeoutMs30,000600,000
A budget covers the whole call, waiting included. Running out answers ActionTimeout naming the check that failed. On a phone, a vision model that is already running when the budget ends is allowed to finish.

Event log

On a browser, each response carries seq, the session event log’s position just before the command acted. Waits that take afterSeq only consider what happened after it, so “click, then wait for the tab it opens” never matches a tab that was already open:
{ "id": 5, "method": "Locator.click", "params": { "locator": { "kind": "text", "value": "Open report" } } }
{ "id": 5, "result": { "resolvedBy": "dom", "bounds": { "x": 812, "y": 431, "width": 120, "height": 40 }, "tookMs": 212, "input": "os" }, "seq": 41 }
{ "id": 6, "method": "Target.waitForTarget", "params": { "afterSeq": 41 } }
The log keeps the last 1,000 events for up to 5 minutes; an older afterSeq answers EventsExpired.

Limits

LimitValue
Script result (browser)1 MiB
File read or write (computer)32 MiB
Process.run output (computer)1 MiB per stream
File.list entries (computer)10,000
Aria snapshot20,000 characters, then cut with a marker line
Selector nesting4 levels
Navigation schemeshttp, https, data, blob and about:blank

Next steps

Drive a session with raw DCP

Open the socket, handshake, and send your first command.

Selectors and strategies

How Locator methods find their target on each kind of session.

Reconnect and resume

Dropped sockets, cursors and idempotency keys.

Locator methods

Every Locator method, its params and its result.