Puppeteer Remote Browser Android: Connect and Automate

Running a Puppeteer remote browser against Android is a common request with a misleading name. Puppeteer does not drive Android devices directly. It drives Chromium over the Chrome DevTools Protocol (CDP). So "Puppeteer remote browser Android" really means one of two things: connecting Puppeteer to a remote Chromium instance that emulates an Android device profile, or connecting to Chrome running on an actual Android device over an exposed CDP endpoint. This post covers both, explains where each breaks down, and shows how to wire Puppeteer to a hosted Chromium session when you need repeatable Android-shaped automation without device farms.

What Puppeteer Actually Does With Android

Puppeteer is a Node library that speaks CDP to a Chromium-based browser. It has no Android-specific transport. There is no puppeteer.connect({ device: 'pixel' }). Everything Android-related in Puppeteer comes from one of three mechanisms:

1. Device emulation via page.emulate() or page.emulateCPUThrottling(), which sets viewport, user agent, touch support, and device scale factor on a desktop Chromium instance.
2. CDP connection to a real Android device where Chrome has been launched with --remote-debugging-port and the port is forwarded to your machine via adb forward.
3. CDP connection to a remote Chromium running in a cloud runtime, with Android emulation applied at the session level.

Only the second option touches real Android hardware. The first and third run desktop Chromium pretending to be Android. That distinction matters more than most tutorials admit, because the two paths fail in different ways.

Why the distinction matters

Device emulation changes what the page sees: viewport dimensions, navigator.userAgent, navigator.maxTouchPoints, ontouchstart presence, device pixel ratio, and a handful of CSS media query results. It does not change the rendering engine, the GPU stack, the font set, or the network stack. A site that fingerprints Android via font metrics, WebGL renderer strings, or TLS behavior will not be fooled by page.emulate().

A real Android device over CDP gives you the actual Chrome for Android build, real touch input, real GPU, and real network conditions. It also gives you adb dependency, device flakiness, USB or network forwarding, and a hard ceiling on parallelism equal to the number of devices you own.

Connecting Puppeteer to a Remote CDP Endpoint

The connection API is the same whether the target is a cloud Chromium session or a locally forwarded Android device. You need a WebSocket debugger URL, which Puppeteer accepts as browserWSEndpoint.

import puppeteer, { Browser, Page } from 'puppeteer-core';

interface RemoteSession {
  wsEndpoint: string;
}

async function connectToRemoteChromium(
  session: RemoteSession
): Promise<{ browser: Browser; page: Page }> {
  const browser = await puppeteer.connect({
    browserWSEndpoint: session.wsEndpoint,
    defaultViewport: null, // let the remote session control viewport
    protocolTimeout: 180_000,
  });

  const context = browser.defaultBrowserContext();
  const page = await context.newPage();

  // Apply an Android-shaped profile on top of the remote session.
  await page.emulate({
    viewport: {
      width: 412,
      height: 915,
      deviceScaleFactor: 2.625,
      isMobile: true,
      hasTouch: true,
      isLandscape: false,
    },
    userAgent:
      'Mozilla/5.0 (Linux; Android 14; Pixel 7) AppleWebKit/537.36 ' +
      '(KHTML, like Gecko) Chrome/124.0.0.0 Mobile Safari/537.36',
  });

  await page.goto('https://example.com', { waitUntil: 'networkidle2' });
  return { browser, page };
}

async function main() {
  const { browser, page } = await connectToRemoteChromium({
    wsEndpoint: process.env.REMOTE_BROWSER_WS!,
  });

  const title = await page.title();
  console.log('Loaded:', title);

  await browser.close(); // closes the session, not your process
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

Two details are easy to get wrong. First, puppeteer.connect does not launch anything, so you must use puppeteer-core and supply the endpoint yourself. Second, browser.close() on a connected browser disconnects and typically terminates the remote session depending on the provider. If you want to keep the session alive for a later run, use browser.disconnect() instead.

For the underlying protocol behavior, the Chrome DevTools Protocol documentation is the authoritative reference for which domains and methods are available on a given target.

Real Android Device vs Emulated Android Profile

The table below summarizes the trade-offs. This is the decision most teams get wrong because they assume emulation is "close enough" until a target site disagrees.

If your goal is verifying that a checkout flow works on a real Pixel, use a device. If your goal is running thousands of agent tasks that need a mobile-shaped viewport and touch events, emulation on a hosted runtime is the cheaper and more reliable path.

The adb Forward Path, and Where It Breaks

For completeness, here is how the real-device path works. You launch Chrome on the device with remote debugging enabled, forward the port, and read the WebSocket URL from the /json/version endpoint.

adb forward tcp:9222 localabstract:chrome_devtools_remote
curl http://localhost:9222/json/version

The response includes a webSocketDebuggerUrl you can pass to puppeteer.connect. In practice this path fails for several predictable reasons:

• Chrome for Android only exposes the abstract socket when the app is debuggable or when you use a Chromium build that permits it. Play Store Chrome restricts this.
• Port forwarding is per-device and per-connection. Scaling past a handful of devices means a device farm with its own orchestration layer.
• Sessions are not isolated. Two scripts hitting the same device share cookies, storage, and tabs unless you manage contexts manually.
• Devices sleep, disconnect, and update. A CI job that depends on a physical device has a non-trivial flake rate that has nothing to do with your code.

This is why most production teams that started with adb forward eventually move the Android-shaped workload to a remote Chromium runtime and reserve physical devices for the narrow set of tests that genuinely require hardware.

Where a Hosted Runtime Fits

A hosted Chromium runtime gives you a CDP endpoint per session. You connect Puppeteer the same way you would to a local Chrome, but the browser lives in the cloud, sessions are isolated, and you can attach a live viewer to watch what the agent or script is doing.

Remote Browser exposes hosted Chromium sessions with CDP access, Playwright/Puppeteer/Selenium compatibility, persistent profiles, configurable browser settings, and a live viewer. For Android-shaped work specifically, the useful properties are:

• Session isolation. Each run gets a clean browser context, so cookies and storage from a previous task do not leak into the next.
• Persistent profiles when you need them. Some flows require a logged-in state across runs. Profiles let you carry that state without re-authenticating every time.
• Configurable browser settings. User agent, locale, timezone, and viewport can be set per session. Note that these are configuration knobs, not a guarantee of evading any particular detection system.
• Live viewer. When a Puppeteer script hangs on an Android-emulated page, watching the session beats guessing from logs.

The remote browser for AI agents post covers the runtime model in more depth, and the documentation has the connection details for each client library.

Choosing between local Chrome and a hosted session

Run Puppeteer against local Chrome when you are iterating on selectors and the page is not sensitive to IP or fingerprint. Move to a hosted session when any of the following is true:

• You need more concurrent sessions than your laptop or CI runner can hold.
• The target site behaves differently from datacenter IPs, and you need proxy configuration.
• You want session replay or a live viewer for debugging.
• You are running agent workloads where each task should start from a clean state.

If you are still deciding on the runtime shape, remote browser online walks through the hosted model, and remote control browser covers the control-plane side.

Production Criteria for Android-Shaped Automation

Before you commit to a path, check your workload against these criteria. They separate a demo from something that survives a week in production.

1. Does the target actually check hardware signals? If it inspects WebGL renderer strings or font metrics, emulation will not pass. Test early with a small script before you build out the pipeline.

2. What is your concurrency ceiling? Device farms cap at device count. Hosted sessions cap at your quota. Know which one you are hitting. Current limits are listed on the pricing page.

3. How do you handle session state? Android emulation on a fresh session means no cookies. If the flow requires login, you need either a persistent profile or a scripted auth step. Both have costs.

4. What happens when a session dies mid-task? Remote sessions can be reclaimed. Your Puppeteer code should treat browser.on('disconnected') as a recoverable event and reconnect rather than crash the worker.

5. Can you observe failures? A live viewer plus CDP screencast is the difference between a five-minute fix and a two-hour investigation. Build the observability in before you need it.

6. Are you respecting the target's terms? Android emulation is often used to reach mobile-only experiences. That is a legitimate use case, but it does not exempt you from rate limits or terms of service.

Common Failure Modes

A few errors show up repeatedly when teams wire Puppeteer to remote Android-shaped sessions.

Protocol error (Target.setAutoAttach): Target closed usually means the session was reclaimed or the endpoint expired. Reconnect with a fresh session rather than retrying the same WebSocket URL.

Touch events not firing happens when hasTouch is set on the viewport but the page's event listeners were registered before emulation was applied. Call page.emulate() before the first page.goto().

User agent mismatch occurs when you set the UA on the page but the remote session has its own UA override at the browser level. Set it in one place, not both.

Slow first paint on emulated mobile is often CPU throttling you did not ask for. Check whether the runtime applies throttling by default and disable it if your workload is not latency-sensitive.

Summary

Puppeteer does not have an Android mode. It has CDP, and Android is either emulated on top of a Chromium session or reached through a real device with a forwarded debugging port. Emulation is cheap, reproducible, and sufficient for viewport- and touch-shaped work. Real devices are necessary only when the target inspects hardware signals. For most production workloads, a hosted Chromium session with an Android-shaped profile gives you the parallelism and isolation that a device farm cannot, without the adb maintenance burden. Start with the documentation to get an endpoint, then decide whether your workload needs hardware.