Container sessions

Container sessions move browser infrastructure out of the host process while keeping tool execution in your application. The harness starts or reuses one warm server container and creates isolated Playwright connections for concurrent runs.

Docker access is privileged infrastructure access. Use these APIs only in a trusted host that is permitted to manage containers.

Start a Playwright container

Use the Playwright session for deterministic Chromium workflows:

import {
  startPlaywrightContainer,
  stopPlaywrightContainer,
} from "@blopai/browser-harness";

const session = await startPlaywrightContainer();

try {
  const context = await session.browser.newContext();
  const page = await context.newPage();
  await page.goto("http://host.docker.internal:3000");
} finally {
  await session.stop();
}

await stopPlaywrightContainer();

session.stop() disconnects the current client but keeps the warm container running. stopPlaywrightContainer() explicitly removes the shared container.

By default, the server publishes a random port on 127.0.0.1 and maps host.docker.internal to the host gateway.

Start a Camoufox container

Use the separate Camoufox session only when its browser fingerprint is needed:

import {
  startCamoufoxContainer,
  stopCamoufoxContainer,
} from "@blopai/browser-harness";

const session = await startCamoufoxContainer();

try {
  const context = await session.browser.newContext({ viewport: null });
  const page = await context.newPage();
  await page.goto("https://example.com");
} finally {
  await session.stop();
}

await stopCamoufoxContainer();

The harness builds a version-derived Camoufox image when no explicit image is configured. It uses a randomized WebSocket path and filters environment values before passing launch options into the container.

Join a shared Docker network

Set a network when the application and browser run in separate containers on the same trusted Docker network:

export BLOP_PLAYWRIGHT_NETWORK=blop-network
export BLOP_CAMOUFOX_NETWORK=blop-network

In shared-network mode, the browser endpoint uses the container name instead of a host-published port. Other containers on that network can reach the server, so don’t attach untrusted workloads.

Configure container images

Use these variables to override container identity and images:

Variable	Purpose
BLOP_PLAYWRIGHT_IMAGE	Override the Playwright image
BLOP_PLAYWRIGHT_CONTAINER	Override the blop-playwright container name
BLOP_PLAYWRIGHT_NETWORK	Join a shared Docker network
BLOP_CONTAINER_DISABLE_CORS_BYPASS	Keep Chromium web security enabled
BLOP_CAMOUFOX_IMAGE	Override the Camoufox image
BLOP_CAMOUFOX_CONTAINER	Override the blop-camoufox container name
BLOP_CAMOUFOX_NETWORK	Join a Camoufox shared network

The Chromium container disables web security by default for cross-origin test flows. Set BLOP_CONTAINER_DISABLE_CORS_BYPASS when the test must preserve the browser’s normal same-origin enforcement.

Next steps

Read the security model before granting a process access to the Docker socket or a shared browser network.