Chrome DevTools for coding agents
/**
* @license
* Copyright 2025 Google LLC
* SPDX-License-Identifier: Apache-2.0
*/
import {execSync} from 'node:child_process';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import type {ReadonlyServerConfig} from './config/ServerConfig.js';
import {
Mutex,
puppeteer,
type Browser,
type ChromeReleaseChannel,
type LaunchOptions,
} from './third_party/index.js';
import {
logger,
puppeteerLogger,
redactConnectOptionsForLogging,
} from './utils/logger.js';
import {isAllowedUrl} from './utils/url.js';
export interface BrowserManagerOptions {
logFile?: fs.WriteStream;
}
/**
* Identity token for an in-flight connect/launch attempt. Instances carry no
* data and are never inspected structurally — only ever compared by
* reference (`!==`) — see BrowserManager#abandonPendingAttempt().
*/
class BrowserAttempt {}
export class BrowserManager {
#browser?: Browser;
#browserMode?: 'launched' | 'connected';
#initPromise?: Promise<Browser>;
#mutex = new Mutex();
#closingCount = 0;
#config: ReadonlyServerConfig;
#options: BrowserManagerOptions;
#browserAttempt: BrowserAttempt = new BrowserAttempt();
constructor(
config: ReadonlyServerConfig,
options: BrowserManagerOptions = {},
) {
this.#config = config;
this.#options = options;
}
static makeTargetFilter(enableExtensions = false) {
return function targetFilter(target: {url(): string}): boolean {
const url = target.url();
if (!url) {
return true;
}
return isAllowedUrl(url, {categoryExtensions: enableExtensions});
};
}
static detectDisplay(): void {
// Only detect display on Linux/UNIX.
if (os.platform() === 'win32' || os.platform() === 'darwin') {
return;
}
if (!process.env['DISPLAY']) {
try {
const result = execSync(
`ps -u $(id -u) -o pid= | xargs -I{} cat /proc/{}/environ 2>/dev/null | tr '\\0' '\\n' | grep -m1 '^DISPLAY=' | cut -d= -f2`,
);
const display = result.toString('utf8').trim();
process.env['DISPLAY'] = display;
} catch {
// no-op
}
}
}
/**
* Chrome refuses to start as root unless the sandbox is explicitly disabled and
* only says so on its stderr. Because we launch with `pipe: true`, Puppeteer
* never surfaces that stderr and the failure reaches the client as an opaque
* `Protocol error (Target.setDiscoverTargets): Target closed`. Detect the
* situation and explain the way out instead. See https://crbug.com/638180.
*
* Returns `undefined` when the failure cannot be explained by running as root,
* including on platforms without uids and when the sandbox was already disabled
* through `--chrome-arg` (in which case root is not what stopped Chrome).
*/
static rootSandboxLaunchError(
error: Error,
args: readonly string[],
uid: number | undefined = process.getuid?.(),
): Error | undefined {
if (uid !== 0) {
return undefined;
}
if (
args.some(
arg => arg === '--no-sandbox' || arg.startsWith('--no-sandbox='),
)
) {
return undefined;
}
return new Error(
`Chrome failed to start: ${error.message}\n\n` +
'chrome-devtools-mcp is running as root and Chrome does not start as root ' +
'(https://crbug.com/638180). Run chrome-devtools-mcp as a non-root user; in a ' +
'container, create an unprivileged user in the image and switch to it with ' +
"USER. For the setup that Chrome's sandbox needs, see " +
'https://pptr.dev/troubleshooting#setting-up-chrome-linux-sandbox.',
{
cause: error,
},
);
}
/**
* Puppeteer reports a headed launch without a display as "Missing X server"
* and suggests its own `headless` option, which users of this server cannot
* set directly. Point them to the `--headless` flag instead.
*
* Returns `undefined` for headless launches and for unrelated failures.
*/
static missingDisplayLaunchError(
error: Error,
headless: boolean,
): Error | undefined {
if (headless || !error.message.includes('Missing X server')) {
return undefined;
}
return new Error(
`Chrome failed to start: ${error.message}\n\n` +
'No X server is available to show a headed Chrome window. Start ' +
'chrome-devtools-mcp with --headless, set DISPLAY to a running X ' +
'server, or run chrome-devtools-mcp under xvfb-run.',
{
cause: error,
},
);
}
async ensureBrowser(): Promise<Browser> {
if (this.#initPromise) {
return await this.#initPromise;
}
const initPromise = this.#ensureBrowserLocked();
this.#initPromise = initPromise;
try {
return await initPromise;
} finally {
if (this.#initPromise === initPromise) {
this.#initPromise = undefined;
}
}
}
async #ensureBrowserLocked(): Promise<Browser> {
if (this.#closingCount > 0) {
throw new Error('Browser was closed while initializing.');
}
// Captured before acquiring #mutex, not after: a caller queued here can
// have its own timeout fire (abandonPendingAttempt()) while it's still
// waiting for the lock. Capturing only after acquiring it would let such
// a call silently adopt the freshly-rotated token as its own baseline
// once the lock frees up, defeating the abandonment check entirely.
const attempt = this.#browserAttempt;
using guard = await this.#mutex.acquire();
if (this.#closingCount > 0) {
throw new Error('Browser was closed while initializing.');
}
if (this.#browserAttempt !== attempt) {
// Abandoned while queued for the lock — #browser was never touched by
// this call, so bail immediately without #closeBrowser(), which could
// otherwise tear down a different, still-current attempt's browser.
throw new Error('Connection attempt was abandoned before it completed.');
}
if (!this.#browser?.connected) {
await this.#initBrowser();
}
if (
this.#closingCount > 0 ||
this.#browserAttempt !== attempt ||
!this.#browser
) {
const reason =
this.#closingCount > 0
? 'Browser was closed while initializing.'
: 'Connection attempt was abandoned before it completed.';
await this.#closeBrowser();
throw new Error(reason);
}
return this.#browser;
}
/**
* Signals that whoever was waiting on the in-flight ensureBrowser() call
* has given up (e.g. a tool-call timeout). There's no way to cancel a
* pending connect()/launch(), so this doesn't stop it — it rotates the
* token to a fresh value and clears #initPromise, so a late-resolving
* attempt gets discarded by #ensureBrowserLocked() instead of silently
* installed for a caller who already walked away.
*
* Also forgets the cached #browser, if any. This only ever fires from a
* getContext()-level timeout, which covers both ensureBrowser() and the
* McpContext initialization built on it — if ensureBrowser() already
* resolved and it's that later step hanging (e.g. a dead CDP transport),
* the token rotation alone does nothing, since #browser is already
* cached. Safe to forget unconditionally here: a tool call that already
* received a Browser keeps using it, so forgetting the cached value only
* makes the next ensureBrowser() reconnect.
*/
abandonPendingAttempt(): void {
this.#browserAttempt = new BrowserAttempt();
this.#initPromise = undefined;
this.#forgetCurrentBrowser();
}
async #initBrowser(): Promise<Browser> {
if (
this.#config.resolved.browserUrl ||
this.#config.resolved.wsEndpoint ||
this.#config.resolved.autoConnect
) {
return await this.#connect();
}
return await this.#launch();
}
async #launch(): Promise<Browser> {
const {
channel,
executablePath,
headless,
isolated = false,
categoryExtensions: enableExtensions,
viaCli,
viewport,
acceptInsecureCerts,
experimentalDevtools: devtools = false,
blockedUrlPattern: blocklist,
allowedUrlPattern: allowlist,
ignoreDefaultChromeArg,
proxyServer,
} = this.#config.resolved;
const profileDirName =
channel && channel !== 'stable'
? `chrome-profile-${channel}`
: 'chrome-profile';
let userDataDir = this.#config.resolved.userDataDir;
if (!isolated && !userDataDir) {
userDataDir = path.join(
os.homedir(),
'.cache',
viaCli ? 'chrome-devtools-mcp-cli' : 'chrome-devtools-mcp',
profileDirName,
);
await fs.promises.mkdir(userDataDir, {
recursive: true,
});
}
const args: LaunchOptions['args'] = [
...(this.#config.resolved.chromeArg ?? []),
];
if (proxyServer) {
args.push(`--proxy-server=${proxyServer}`);
}
args.push('--hide-crash-restore-bubble');
const ignoreDefaultArgs: LaunchOptions['ignoreDefaultArgs'] =
ignoreDefaultChromeArg ?? false;
if (headless) {
args.push('--screen-info={3840x2160}');
}
let puppeteerChannel: ChromeReleaseChannel | undefined;
if (devtools) {
args.push('--auto-open-devtools-for-tabs');
}
if (!executablePath) {
puppeteerChannel =
channel && channel !== 'stable' ? `chrome-${channel}` : 'chrome';
}
if (!headless) {
BrowserManager.detectDisplay();
}
let browser: Browser | undefined;
try {
browser = await puppeteer.launch({
channel: puppeteerChannel,
targetFilter: BrowserManager.makeTargetFilter(enableExtensions),
executablePath,
defaultViewport: null,
userDataDir,
pipe: true,
headless,
args,
ignoreDefaultArgs,
acceptInsecureCerts,
handleDevToolsAsPage: true,
enableExtensions,
blocklist,
allowlist,
logger: puppeteerLogger,
// The entry points own signal handling and call close(), which
// closes the browser gracefully. Puppeteer's handlers would SIGKILL
// Chrome synchronously on the same signal and win the race.
handleSIGINT: false,
handleSIGTERM: false,
handleSIGHUP: false,
});
if (this.#options.logFile) {
// FIXME: we are probably subscribing too late to catch startup logs. We
// should expose the process earlier or expose the getRecentLogs() getter.
browser.process()?.stderr?.pipe(this.#options.logFile);
browser.process()?.stdout?.pipe(this.#options.logFile);
}
if (viewport) {
const [page] = await browser.pages();
await page?.resize({
contentWidth: viewport.width,
contentHeight: viewport.height,
});
}
this.#browserMode = 'launched';
this.#browser = browser;
const launched = browser;
launched.once('disconnected', () => this.#evictIfCurrent(launched));
return launched;
} catch (error) {
await browser?.close().catch(() => {
// Best-effort cleanup if post-launch setup failed.
});
if (
userDataDir &&
error instanceof Error &&
error.message.includes('The browser is already running')
) {
throw new Error(
`The browser is already running for ${userDataDir}. Use --isolated to run multiple browser instances.`,
{
cause: error,
},
);
}
if (error instanceof Error) {
const rootError = BrowserManager.rootSandboxLaunchError(error, args);
if (rootError) {
throw rootError;
}
const displayError = BrowserManager.missingDisplayLaunchError(
error,
headless,
);
if (displayError) {
throw displayError;
}
}
throw error;
}
}
async #connect(): Promise<Browser> {
const {
browserUrl: browserURL,
wsEndpoint,
wsHeaders,
autoConnect: isAutoConnect,
userDataDir,
blockedUrlPattern: blocklist,
allowedUrlPattern: allowlist,
categoryExtensions: enableExtensions,
} = this.#config.resolved;
// Important: only pass channel, if autoConnect is true.
const channel = isAutoConnect ? this.#config.resolved.channel : undefined;
const connectOptions: Parameters<typeof puppeteer.connect>[0] = {
targetFilter: BrowserManager.makeTargetFilter(enableExtensions),
defaultViewport: null,
handleDevToolsAsPage: true,
blocklist,
allowlist,
logger: puppeteerLogger,
// Detects a transport that died without a close frame (e.g. an adb
// port-forward torn down mid-call). Puppeteer pings the socket
// periodically and terminates it on a missed pong, which rejects the
// in-flight CDP calls and fires `disconnected` so #evictIfCurrent()
// drops the stale handle. Without this, such a call would hang until
// protocolTimeout inside the context queue.
wsOptions: {
keepAlive: true,
headers: wsHeaders,
},
};
let autoConnect = false;
if (wsEndpoint) {
connectOptions.browserWSEndpoint = wsEndpoint;
} else if (browserURL) {
connectOptions.browserURL = browserURL;
} else if (channel || userDataDir) {
autoConnect = true;
if (userDataDir) {
// TODO: re-expose this logic via Puppeteer.
const portPath = path.join(userDataDir, 'DevToolsActivePort');
try {
const fileContent = await fs.promises.readFile(portPath, 'utf8');
const [rawPort, rawPath] = fileContent
.split('\n')
.map(line => {
return line.trim();
})
.filter(line => {
return !!line;
});
if (!rawPort || !rawPath) {
throw new Error(
`Invalid DevToolsActivePort '${fileContent}' found`,
);
}
const port = parseInt(rawPort, 10);
if (isNaN(port) || port <= 0 || port > 65535) {
throw new Error(`Invalid port '${rawPort}' found`);
}
const browserWSEndpoint = `ws://127.0.0.1:${port}${rawPath}`;
connectOptions.browserWSEndpoint = browserWSEndpoint;
} catch (error) {
throw new Error(
`Could not connect to Chrome in ${userDataDir}. Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.`,
{
cause: error,
},
);
}
} else {
if (!channel) {
throw new Error('Channel must be provided if userDataDir is missing');
}
connectOptions.channel =
channel === 'stable' ? 'chrome' : `chrome-${channel}`;
}
} else {
throw new Error(
'Either browserURL, wsEndpoint, channel or userDataDir must be provided',
);
}
logger?.(
'Connecting Puppeteer to ',
JSON.stringify(redactConnectOptionsForLogging(connectOptions)),
);
try {
const connected = await puppeteer.connect(connectOptions);
logger?.('Connected Puppeteer');
this.#browserMode = 'connected';
this.#browser = connected;
connected.once('disconnected', () => this.#evictIfCurrent(connected));
return connected;
} catch (err) {
throw new Error(
`Could not connect to Chrome. ${autoConnect ? `Check if Chrome is running and remote debugging is enabled by going to chrome://inspect/#remote-debugging.` : `Check if Chrome is running.`}`,
{
cause: err,
},
);
}
}
/**
* Drops the cached browser handle so the next ensureBrowser() call
* establishes a fresh connection. Only called from abandonPendingAttempt()
* when a getContext()-level timeout fires after ensureBrowser() already
* resolved, which means the handle looks connected but its CDP
* initialization is hanging.
*
* Also tears the browser down in the background: closes it if it was
* launched (so the Chrome subprocess doesn't leak), or disconnects if it
* was only connected to (so the transport and its listeners don't leak).
* Puppeteer's connection disposal rejects any in-flight CDP call, so a hung
* call settles instead of leaking forever.
*/
#forgetCurrentBrowser(): void {
const browser = this.#browser;
if (!browser) {
return;
}
const mode = this.#browserMode;
this.#browser = undefined;
this.#browserMode = undefined;
if (mode === 'launched') {
void this.#closeLaunchedBrowser(browser);
} else {
void browser.disconnect().catch(err => {
logger?.('Failed to disconnect forgotten browser', err);
});
}
}
/**
* Handles a `disconnected` event fired by a browser we hold: clears the
* cached handle if it's still the current one, so the next ensureBrowser()
* call reconnects proactively rather than only discovering the staleness
* lazily on the next call's `!this.#browser?.connected` check. No teardown
* here — the browser is already disconnected/closed, that's why this
* fired. The identity guard makes a `disconnected` that fires late on an
* already-superseded browser a safe no-op.
*/
#evictIfCurrent(candidate: Browser): void {
if (this.#browser !== candidate) {
return;
}
this.#browser = undefined;
this.#browserMode = undefined;
}
async #closeLaunchedBrowser(browser: Browser): Promise<void> {
let timer: ReturnType<typeof setTimeout> | undefined;
try {
await Promise.race([
browser.close(),
new Promise<never>((_, reject) => {
timer = setTimeout(
() => reject(new Error('Timed out closing browser')),
5_000,
);
timer.unref?.();
}),
]);
} catch (err) {
logger?.('Failed to close browser', err);
browser.process()?.kill('SIGKILL');
} finally {
clearTimeout(timer);
}
}
async #closeBrowser(): Promise<void> {
const browser = this.#browser;
const mode = this.#browserMode;
this.#browser = undefined;
this.#browserMode = undefined;
if (!browser || !browser.connected) {
return;
}
if (mode === 'launched') {
await this.#closeLaunchedBrowser(browser);
return;
}
await browser.disconnect().catch(err => {
logger?.('Failed to disconnect from browser', err);
});
}
/**
* Shutdown hook for the active browser. Closes a launched browser (so the
* Chrome subprocess is reaped) or disconnects from an attached browser (so
* the user's Chrome instance stays alive). No-op if no browser is active or
* the connection has already been dropped.
*/
async close(): Promise<void> {
this.#initPromise = undefined;
this.#closingCount++;
using guard = await this.#mutex.acquire();
try {
await this.#closeBrowser();
} finally {
this.#closingCount--;
}
}
[Symbol.dispose](): void {
this.close().catch(err => {
logger?.('Failed to dispose BrowserManager', err);
});
}
async [Symbol.asyncDispose](): Promise<void> {
await this.close();
}
}