Container sessions

Run the browser in a warm Docker container while your application keeps running the tools. Browser Harness starts or reuses one server container and gives each run its own browser connection, so concurrent runs share the container.

Prerequisites

• The TypeScript API installed.
• Docker, on a trusted host. Docker access is privileged: it can start containers, mount host paths and change local infrastructure.

Run a Playwright container

1. Start a session, open a page and disconnect when done:

   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();
   }

   session.stop() disconnects this run and keeps the container warm. The server publishes a random port on 127.0.0.1, and host.docker.internal reaches the host.

2. Remove the shared container when no run needs it:

   await stopPlaywrightContainer();

Run a Camoufox container

Use startCamoufoxContainer() and stopCamoufoxContainer() the same way, only when you need the Camoufox fingerprint. Create contexts with { viewport: null }. Without an image override, Browser Harness builds a local image matched to its versions. The server uses a random WebSocket path, and only Camoufox settings pass from the environment into the browser launch.

Check it worked

While a container is warm, Docker lists it:

docker ps --filter name=blop-playwright

Join a shared Docker network

When your app and the browser run in separate containers, put both on one trusted network:

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

The browser endpoint then uses the container name instead of a published port. Every container on that network can reach the browser server, so do not attach untrusted workloads.

Container environment variables

Variable	Default	Effect
BLOP_PLAYWRIGHT_IMAGE	mcr.microsoft.com/playwright matching the Playwright version	Playwright image
BLOP_PLAYWRIGHT_CONTAINER	blop-playwright	Playwright container name
BLOP_PLAYWRIGHT_NETWORK	unset	Shared Docker network
BLOP_CONTAINER_DISABLE_CORS_BYPASS	unset	Any non-empty value keeps Chromium’s same-origin enforcement on
BLOP_CAMOUFOX_IMAGE	locally built image	Camoufox image
BLOP_CAMOUFOX_CONTAINER	blop-camoufox	Camoufox container name
BLOP_CAMOUFOX_NETWORK	BLOP_PLAYWRIGHT_NETWORK	Camoufox Docker network

The Playwright container disables Chromium web security by default so runs can cross origins, for example OAuth redirects and third-party iframes. Set BLOP_CONTAINER_DISABLE_CORS_BYPASS when same-origin behaviour is part of what you test.

Next

• Security model