Browser Automation

Mobilerun exposes a per-device WebSocket that reverse-proxies Chrome-for-Android’s DevTools (CDP) endpoint. Off-the-shelf browser automation libraries — Puppeteer and Playwright — connect to it with a single URL, just like they would to a local Chrome instance. Use this when you want to script Chrome on a device directly (navigate, evaluate JavaScript, intercept network requests, scrape content) instead of going through the agent.

Endpoint

wss://api.mobilerun.ai/v1/devices/{deviceId}/browser/cdp

The endpoint is a browser-level CDP socket. Pages are multiplexed over the CDP Target domain — you do not need a separate URL per tab.

Authentication

Pass your Mobilerun API key as a request header during the WebSocket handshake:

Authorization: Bearer dr_sk_YOUR_API_KEY

Always send the key as a header. Never put credentials in the URL — query-string tokens leak into logs, traces, and proxy access records.

Requirements

The device must be in the ready state. See Devices for state details.
Chrome must be installed and have remote debugging available on the device. If Chrome’s CDP socket is not reachable, the connection fails at handshake with a clear error.
You need a Mobilerun API key.

Connect with Puppeteer

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://api.mobilerun.ai/v1/devices/${deviceId}/browser/cdp`,
  headers: {
    Authorization: `Bearer ${process.env.MOBILERUN_API_KEY}`,
  },
});

const page = await browser.newPage();
await page.goto('https://example.com');
const title = await page.title();
console.log(title);

await browser.disconnect();

Connect with Playwright

import { chromium } from 'playwright';

const browser = await chromium.connectOverCDP(
  `wss://api.mobilerun.ai/v1/devices/${deviceId}/browser/cdp`,
  {
    headers: {
      Authorization: `Bearer ${process.env.MOBILERUN_API_KEY}`,
    },
  }
);

const context = browser.contexts()[0] ?? await browser.newContext();
const page = await context.newPage();
await page.goto('https://example.com');
console.log(await page.title());

await browser.close();

How it works

The endpoint transparently bridges the WebSocket to Chrome’s chrome_devtools_remote socket on the device. There is no local port forwarding to set up and no separate ADB tunnel to manage — once the device is connected to Mobilerun, the CDP endpoint is available automatically on every adb-backed device type (Cloud Phone and Physical Phone). Standard CDP semantics apply: connect once at the browser level, then attach to individual tabs through Target.getTargets / Target.attachToTarget (Puppeteer and Playwright handle this for you).

Limitations

Chrome only. WebView debugging (webview_devtools_remote_<pid>) is not exposed.
Browser-level only. There is no per-page /json/list proxy — use the CDP Target domain to enumerate and attach to pages.
Chrome must be debuggable. A device without an active Chrome CDP socket fails at connect time.

Introduction

Concepts

Guides

Dashboard

Integrations

Browser Automation

Endpoint

Authentication

Requirements

Connect with Puppeteer

Connect with Playwright

How it works

Limitations

​Endpoint

​Authentication

​Requirements

​Connect with Puppeteer

​Connect with Playwright

​How it works

​Limitations

Endpoint

Authentication

Requirements

Connect with Puppeteer

Connect with Playwright

How it works

Limitations