Skip to content

Write HTML. Render video. Built for agents.

fix(cli): Chrome starts inside an agent's macOS sandbox as one process over a pipe (#5781)

Miguel Ángel5e7ba0be944b
diff --git a/packages/cli/src/browser/launch.ts b/packages/cli/src/browser/launch.ts
index 9318210313..4417f9b094 100644
--- a/packages/cli/src/browser/launch.ts
+++ b/packages/cli/src/browser/launch.ts
@@ -7,7 +7,13 @@ import {
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import { requestCliExit } from "../utils/commandResult.js";
import { processIsAlive } from "../utils/processTree.js";
-import { sandboxDeniedRemediation } from "./sandboxDenied.js";
+import {
+ inAgentSandbox,
+ isOneProcessOverPipe,
+ machServiceDenied,
+ oneProcessOverPipe,
+ sandboxDeniedRemediation,
+} from "./sandboxDenied.js";
export class BrowserCleanupError extends AggregateError {}
@@ -56,9 +62,7 @@ export async function resolveManagedGpuMode(
context.signal?.throwIfAborted();
const browser = await launchManagedBrowser(puppeteer, {
...options,
- ...(context.noListen
- ? { pipe: true, args: [...(options.args ?? []), "--single-process"] }
- : {}),
+ ...(context.noListen ? oneProcessOverPipe(options) : {}),
signal: context.signal,
});
try {
@@ -76,6 +80,29 @@ export async function resolveManagedGpuMode(
export async function launchManagedBrowser(
puppeteer: PuppeteerNode,
options: LaunchOptions,
+): Promise<Browser> {
+ const sandboxed = isOneProcessOverPipe(options) || inAgentSandbox();
+ try {
+ return await launchOwnedBrowser(puppeteer, sandboxed ? oneProcessOverPipe(options) : options);
+ } catch (error) {
+ const unnamedSeatbelt = !sandboxed && machServiceDenied(normalizeErrorMessage(error));
+ if (!unnamedSeatbelt) throw withRemediation(error);
+ return launchOwnedBrowser(puppeteer, oneProcessOverPipe(options)).catch(
+ (retryError: unknown) => {
+ throw withRemediation(retryError);
+ },
+ );
+ }
+}
+
+function withRemediation(error: unknown): unknown {
+ const remediation = sandboxDeniedRemediation(normalizeErrorMessage(error));
+ return remediation ? new Error(remediation, { cause: error }) : error;
+}
+
+async function launchOwnedBrowser(
+ puppeteer: PuppeteerNode,
+ options: LaunchOptions,
): Promise<Browser> {
if (shutdown) throw new Error("The CLI is stopping; no browser can start.");
ownSignals();
@@ -95,9 +122,6 @@ export async function launchManagedBrowser(
browsers.add(browser);
child.once("exit", () => browsers.delete(browser));
return browser;
- } catch (error) {
- const remediation = sandboxDeniedRemediation(normalizeErrorMessage(error));
- throw remediation ? new Error(remediation, { cause: error }) : error;
} finally {
pending.delete(launch);
}
diff --git a/packages/cli/src/browser/sandboxDenied.test.ts b/packages/cli/src/browser/sandboxDenied.test.ts
index 826bb58926..d5a63b3f32 100644
--- a/packages/cli/src/browser/sandboxDenied.test.ts
+++ b/packages/cli/src/browser/sandboxDenied.test.ts
@@ -1,5 +1,6 @@
-import type { LaunchOptions, PuppeteerNode } from "puppeteer-core";
-import { describe, expect, it } from "vitest";
+import { EventEmitter } from "node:events";
+import type { Browser, LaunchOptions, PuppeteerNode } from "puppeteer-core";
+import { afterEach, describe, expect, it, vi } from "vitest";
import { launchManagedBrowser } from "./launch.js";
const SEATBELT_LAUNCH_FAILURE = [
@@ -28,3 +29,43 @@ describe("a browser launch a sandbox refuses", () => {
await expect(launchManagedBrowser(failingPuppeteer(other), {})).rejects.toThrow(other);
});
});
+
+const fakeBrowser = () => ({ process: () => new EventEmitter() }) as unknown as Browser;
+
+function recordingPuppeteer(failures: string[]) {
+ const launches: LaunchOptions[] = [];
+ const puppeteer = {
+ launch: async (options: LaunchOptions) => {
+ launches.push(options);
+ const failure = failures.shift();
+ if (failure) throw new Error(failure);
+ return fakeBrowser();
+ },
+ } as unknown as PuppeteerNode;
+ return { puppeteer, launches };
+}
+
+describe("a browser inside an agent's macOS seatbelt", () => {
+ const platform = process.platform;
+ afterEach(() => {
+ vi.unstubAllEnvs();
+ Object.defineProperty(process, "platform", { value: platform });
+ });
+
+ it("starts as one process over a pipe when Codex names its seatbelt", async () => {
+ vi.stubEnv("CODEX_SANDBOX", "seatbelt");
+ Object.defineProperty(process, "platform", { value: "darwin" });
+ const { puppeteer, launches } = recordingPuppeteer([]);
+ await launchManagedBrowser(puppeteer, { args: ["--headless"] });
+ expect(launches).toHaveLength(1);
+ expect(launches[0]).toMatchObject({ pipe: true, args: ["--headless", "--single-process"] });
+ });
+
+ it("relaunches as one process over a pipe when an unnamed sandbox refuses the mach service", async () => {
+ vi.stubEnv("CODEX_SANDBOX", "");
+ const { puppeteer, launches } = recordingPuppeteer([SEATBELT_LAUNCH_FAILURE]);
+ await expect(launchManagedBrowser(puppeteer, { args: ["--headless"] })).resolves.toBeDefined();
+ expect(launches.map((options) => options.pipe ?? false)).toEqual([false, true]);
+ expect(launches[1]!.args).toEqual(["--headless", "--single-process"]);
+ });
+});
diff --git a/packages/cli/src/browser/sandboxDenied.ts b/packages/cli/src/browser/sandboxDenied.ts
index 577f147c66..2268846be2 100644
--- a/packages/cli/src/browser/sandboxDenied.ts
+++ b/packages/cli/src/browser/sandboxDenied.ts
@@ -1,8 +1,34 @@
+import type { LaunchOptions } from "puppeteer-core";
+
const MACH_SERVICE_DENIED = /bootstrap_check_in\b[^\n]*Permission denied/;
+const SINGLE_PROCESS = "--single-process";
+
+export function machServiceDenied(errorMessage: string): boolean {
+ return MACH_SERVICE_DENIED.test(errorMessage);
+}
+
+/** Codex runs agent commands in a macOS seatbelt, which names itself in the environment. */
+export function inAgentSandbox(env = process.env, platform = process.platform): boolean {
+ return platform === "darwin" && env.CODEX_SANDBOX === "seatbelt";
+}
+
+/** The one launch a seatbelt allows: no child process can register its mach port and nothing may listen. */
+export function oneProcessOverPipe(options: LaunchOptions): LaunchOptions {
+ const args = options.args ?? [];
+ return {
+ ...options,
+ pipe: true,
+ args: args.includes(SINGLE_PROCESS) ? args : [...args, SINGLE_PROCESS],
+ };
+}
+
+export function isOneProcessOverPipe(options: LaunchOptions): boolean {
+ return options.pipe === true && (options.args ?? []).includes(SINGLE_PROCESS);
+}
/** A process sandbox (an agent's macOS seatbelt) refused Chrome its mach service, so no browser starts here. */
export function sandboxDeniedRemediation(errorMessage: string): string | undefined {
- if (!MACH_SERVICE_DENIED.test(errorMessage)) return undefined;
+ if (!machServiceDenied(errorMessage)) return undefined;
return [
"The browser can't start inside this sandbox: macOS refused Chrome's mach service (bootstrap_check_in: Permission denied).",
"Rerun this command with escalation, outside the sandbox.",
diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.ts
index 5321d4fbaf..7a1406004b 100644
--- a/packages/cli/src/capture/captureCompositionFrame.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.ts
@@ -3,6 +3,7 @@ import {
launchManagedBrowser,
resolveManagedGpuMode,
} from "../browser/launch.js";
+import { oneProcessOverPipe } from "../browser/sandboxDenied.js";
import { spawn } from "node:child_process";
import type { Browser, Page } from "puppeteer-core";
import type { InProcessRequest, InProcessResponse } from "../utils/staticProjectServer.js";
@@ -230,7 +231,7 @@ export async function openSettledCompositionPage(
headless: true,
signal: options.signal,
executablePath,
- ...(answer ? { pipe: true, args: [...args, "--single-process"] } : { args }),
+ ...(answer ? oneProcessOverPipe({ args }) : { args }),
});
};