The profiles here need OpenShell 0.1.8 or newer. They were tested on 0.1.8: REST, BrowserQL, Puppeteer, Playwright (CDP and native), durable sessions, the LON and AMS regions, the hosted MCP server, and the Stripe Link approval flow. Earlier releases are not supported.
CI lints and imports every profile, and starts a sandbox with a provider built from each to check that the gateway accepts its policy, against the latest OpenShell release and against 0.1.8 on each pull request and once a week.
Two 0.1.8 changes shape the main profile:
- REST endpoints refuse WebSocket upgrades. CDP and Playwright connections need endpoints with
protocol: websocket. The main profile declares one for each CDP and Playwright connect path, and for the worker-pinned/e/<id>/…session and reconnect URLs that the API returns. Any other WebSocket path is refused. - Credentials resolve only where the profile places them.
BROWSERLESS_TOKENresolves only as thetokenquery parameter, including for the MCP server. A placeholder sent in a header or a request body is not replaced.
A gateway keeps the profile it imported; editing the YAML afterwards changes nothing. Importing a profile that already exists fails, so to load a newer version, delete it and import it again (openshell provider profile delete --global browserless, then the import). Providers created from it keep working.
- Bring your own image. OpenShell's default sandbox image has no
curl,nodeorpython. Pass--fromwith an image that has your client, such asnode:26-trixie-slimor the image built fromexamples/Dockerfile. - Install code where the sandbox can read it. The default filesystem policy does not allow reads under
/opt. Put scripts andnode_modulesunder/usr(the examples image uses/usr/local/lib/browserless-examples) or in the sandbox working directory, or pass a policy that allows your path. - Match
binariesto your image. The profile lets onlynodeandcurlat/usr/binor/usr/local/binreach Browserless. Add your paths if your client lives elsewhere. - macOS VM driver. On 0.1.8 the VM driver could not prepare images published with Docker's v2 manifest format, such as
curlimages/curl. Images published with an OCI index, such as the officialnodeimages, work.
- MCP revision. OpenShell accepts MCP revision
2025-11-25by default. A client that negotiates an older revision, such as2025-06-18, getsmcp_protocol_version_not_allowed. Use a client that supports2025-11-25, such as the MCP SDK version pinned inexamples/, or allow more revisions with the endpoint'smcp.versionssetting in OpenShell's policy schema. - Message size. OpenShell inspects every client WebSocket message and closes the connection on a message over 4 MiB (measured on 0.1.8: 3.9 MiB passes, 4.1 MiB closes). Everyday CDP traffic from Puppeteer and Playwright stays far below that. Large
page.evaluatearguments orpage.setContentpayloads can hit it.