For AI agents: a documentation index is available at /llms.txt
Skip to main content

Using Browserless from NVIDIA OpenShell sandboxes

NVIDIA OpenShell runs AI agents in sandboxes that keep credentials out of the agent's reach. This guide imports the Browserless provider profile into OpenShell, so an agent in a sandbox can use REST, BrowserQL, Puppeteer, Playwright and the hosted MCP server while your API token stays in the OpenShell gateway.

Prerequisites
  • A Browserless API token from your account dashboard
  • OpenShell 0.1.8 or newer with a running gateway. openshell status should show Connected
  • A sandbox image with Node.js, such as node:26-trixie-slim for the quick check. OpenShell's default sandbox image has no node or curl
  • For the client examples, an image with puppeteer-core, playwright-core or @modelcontextprotocol/sdk installed. The repository's examples image has all three, at pinned versions
  • Familiarity with OpenShell providers

How it works​

An OpenShell provider profile declares where a credential may be sent. The Browserless profile lives in the public browserless/openshell repository. It declares one credential, BROWSERLESS_TOKEN, and the Browserless hosts it may go to: production-*.browserless.io and mcp.browserless.io.

Inside the sandbox, BROWSERLESS_TOKEN holds a placeholder, not your token. OpenShell swaps in the real token only when the placeholder is the token query parameter on a request to one of those hosts. Your agent's code connects to Browserless the usual way, with ?token=${process.env.BROWSERLESS_TOKEN}, but the token itself never enters the sandbox.

Use this setup when your agent runs in OpenShell 0.1.8 or newer. If you run NemoClaw, it pins an older OpenShell release, so use its hosted MCP route instead.

Set up the Browserless provider​

  1. Import the profile

    Import the profile straight from the repository. You run this once per gateway:

    openshell provider profile import --global \
    --url https://raw.githubusercontent.com/browserless/openshell/main/providers/browserless.yaml

    Response:

    Imported 1 provider profile.

    To keep the profile from changing under you, replace main in the URL with a commit SHA from the repository.

  2. Create the provider

    Create a provider from the profile with your API token. OpenShell keeps the token in the gateway and hands sandboxes a placeholder:

    export BROWSERLESS_TOKEN=YOUR_API_TOKEN_HERE
    openshell provider create --name browserless --type browserless \
    --credential BROWSERLESS_TOKEN

    Response:

    ✓ Created provider browserless
  3. Run a quick check

    Start a throwaway sandbox with the provider attached and fetch example.com through the Browserless /content API:

    openshell sandbox create --no-keep --from node:26-trixie-slim --provider browserless -- node -e '
    fetch(`https://production-sfo.browserless.io/content?token=${process.env.BROWSERLESS_TOKEN}`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ url: "https://example.com" }),
    }).then((r) => r.text()).then(console.log)'

    Keep the single quotes. They stop your shell from expanding ${process.env.BROWSERLESS_TOKEN}, so it's read inside the sandbox, where it holds the placeholder.

    Response:

    <!DOCTYPE html><html lang="en"><head><meta charset="utf-8"> ... <title>Example Domain</title> ...

From here, attach the provider to your own sandboxes with --provider browserless on openshell sandbox create.

Connect from inside the sandbox​

Every client sends the placeholder from BROWSERLESS_TOKEN as the token query parameter. That's the only place OpenShell replaces it, so a placeholder in a header or a request body reaches Browserless unchanged and gets rejected.

import puppeteer from 'puppeteer-core';

const region = process.env.BROWSERLESS_REGION ?? 'production-sfo';
const token = encodeURIComponent(process.env.BROWSERLESS_TOKEN ?? '');

const browser = await puppeteer.connect({
browserWSEndpoint: `wss://${region}.browserless.io?token=${token}`,
});
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(`puppeteer: ${await page.title()}`);
} finally {
await browser.close();
}

Response:

puppeteer: Example Domain

Set BROWSERLESS_REGION to production-lon or production-ams to use another region.

Run the examples in a sandbox​

The sandbox's network policy blocks package registries, so the clients have to be in the image before the sandbox starts. The repository's examples/ folder holds these scripts and a Dockerfile that installs them, with pinned client versions, under /usr/local/lib/browserless-examples:

git clone https://github.com/browserless/openshell.git && cd openshell
docker build -t browserless-openshell-examples examples
openshell sandbox create --no-keep --from browserless-openshell-examples \
--provider browserless -- sh -c '
cd /usr/local/lib/browserless-examples
node puppeteer.mjs && node playwright.mjs && node browserql.mjs && node mcp.mjs'

Response:

puppeteer: Example Domain
playwright (CDP): Example Domain
playwright (native): Example Domain
browserql: 200 Example Domain
mcp: 23 tools
mcp smartscraper: Example Domain found

What the profile allows​

The profile keeps the agent to browsing through Browserless:

  • Hosts: the token goes only to production-*.browserless.io (the SFO, LON and AMS regions) and mcp.browserless.io/mcp. OpenShell's default sandbox policy blocks requests to any other host. Rules that your own sandbox policy adds for other hosts still apply, but OpenShell never puts the token on those requests.
  • Processes: only node and curl at /usr/bin or /usr/local/bin can reach those hosts. If your client lives elsewhere, import an edited copy of the profile with your paths in binaries.
  • REST: full access, including DELETE so an agent can stop its own sessions. The endpoints that run your own code in the browser (/function, /download) and the server configuration endpoint (/config) aren't available.
  • BrowserQL: every query and mutation except reconnect, sent as a single anonymous operation. reconnect hands the live browser to another client. To keep a browser between connections, use a durable session (POST /session) and the connect and BrowserQL URLs it returns.
  • WebSockets: only the CDP and Playwright connect paths, plus the worker-pinned session and reconnect URLs the API returns.
  • MCP: every tool except browserless_function and the two Stripe Link payment tools, browserless_link_checkout and browserless_link_connect.

Usage is billed to the Browserless account that owns the token, the same as outside OpenShell.

The Stripe Link deny rules cover the MCP tools only. REST stays open, including Browserless's own agent endpoints, which can use a Stripe Link wallet connected to your account. If your account has a connected wallet, use the repository's Link-gated profiles instead. They limit REST to an allow-list and let the wallet tool through only after a person approves it.

NemoClaw​

NemoClaw runs OpenClaw inside an OpenShell sandbox. It pins an OpenShell release older than 0.1.8, so the provider profile above doesn't apply to it. Add the hosted Browserless MCP server through NemoClaw's own MCP support instead:

export BROWSERLESS_TOKEN=YOUR_API_TOKEN_HERE
nemoclaw <sandbox> mcp add browserless --url https://mcp.browserless.io/mcp \
--env BROWSERLESS_TOKEN \
--deny-tool browserless_link_checkout --deny-tool browserless_link_connect \
--deny-tool browserless_function
unset BROWSERLESS_TOKEN

Response:

MCP server 'browserless' added to sandbox '<sandbox>'.

NemoClaw then checks that the credential resolves and prints the result. --env BROWSERLESS_TOKEN reads the token from your shell and stores it as an OpenShell provider, so you can unset it afterwards. The sandbox only sees a placeholder. Check the server with nemoclaw <sandbox> mcp status browserless. The agent gets every other Browserless MCP tool, including browserless_agent for multi-step browsing and browserless_smartscraper for single pages.

Puppeteer, Playwright and OpenClaw's built-in browser connect over a WebSocket, which needs OpenShell 0.1.8 or newer. Run them in an OpenShell sandbox outside NemoClaw until NemoClaw moves to a newer OpenShell release.

Version notes and limits​

  • OpenShell 0.1.8 or newer: 0.1.8 refuses WebSocket upgrades on REST endpoints and resolves credentials only where the profile places them. The profile is written for those rules, and earlier releases aren't supported.

  • Updating the profile: a gateway keeps the profile it imported, and importing a profile that already exists fails. To load a newer version, delete it and import it again. Providers created from it keep working:

    openshell provider profile delete --global browserless
    openshell provider profile import --global \
    --url https://raw.githubusercontent.com/browserless/openshell/main/providers/browserless.yaml

    Response:

    ✓ Deleted provider profile browserless
    Imported 1 provider profile.
  • Sandbox images: OpenShell's default filesystem policy blocks reads under /opt. Install scripts and node_modules under /usr, as the examples image does with /usr/local/lib/browserless-examples, or in the sandbox working directory.

  • Message size: OpenShell inspects every client WebSocket message and closes the connection on one over 4 MiB. Everyday CDP traffic stays far below that, but large page.evaluate arguments or page.setContent payloads can hit it.

FAQ & Troubleshooting​

A request from the sandbox gets 403 with policy_denied

The request falls outside the profile, and OpenShell refused it before it reached Browserless. The response body names the matching rule and a detail. The usual causes are a host other than the Browserless ones above, /function, /download or /config, a BrowserQL reconnect mutation or named operation, the browserless_function or Stripe Link MCP tools, and WebSocket paths other than the connect and reconnect URLs. See What the profile allows.

Browserless rejects the token from inside the sandbox

Send the placeholder as the token query parameter. OpenShell replaces it only there, so a placeholder in an Authorization header or a request body reaches Browserless unchanged. Also check that the sandbox was created with --provider browserless, or the placeholder isn't set at all.

openshell provider profile import fails because the profile already exists

Delete the profile, then import it again, as shown in Version notes and limits. The update command needs the profile's resource_version, which only an exported copy has, so delete and import is simpler. Providers created from the profile keep working.

node or curl isn't found in the sandbox

OpenShell's default sandbox image has neither. Pass --from with an image that has your client, such as node:26-trixie-slim or the image built from the repository's examples Dockerfile.

Scripts under /opt fail with EACCES

The default filesystem policy doesn't allow reads under /opt. Install your scripts and node_modules under /usr/local/lib or in the sandbox working directory, or pass a policy that allows your path.

The MCP client fails with mcp_protocol_version_not_allowed

Your client negotiated an MCP revision older than 2025-11-25, which is the only one OpenShell accepts by default. Update the client, or allow more revisions with the mcp.versions setting on the MCP endpoint in OpenShell's policy schema.

OpenClaw in an OpenShell sandbox refuses to open any page

Allow the RFC 2544 benchmark range in OpenClaw's browser settings, and point the Browserless profile at the sandbox's placeholder:

// ~/.openclaw/openclaw.json inside the sandbox.
{
browser: {
enabled: true,
defaultProfile: "browserless",
profiles: {
browserless: {
// OpenClaw fills in BROWSERLESS_TOKEN from the sandbox environment, where it holds the placeholder.
cdpUrl: "wss://production-sfo.browserless.io?token=${BROWSERLESS_TOKEN}",
},
},
// OpenShell answers DNS from this range, so OpenClaw has to allow it.
ssrfPolicy: { allowRfc2544BenchmarkRange: true },
},
}

Inside an OpenShell sandbox, DNS lookups return addresses from 198.18.0.0/15, and OpenShell routes the traffic from there. OpenClaw's SSRF guard blocks that range by default, so every hostname looks like a private address until you allow it. Don't paste your real API token into openclaw.json in the sandbox. The placeholder is what keeps the token in the OpenShell gateway.

ssrfPolicy is a documented OpenClaw setting, so the validator accepts it:

openclaw config validate

Response:

Config valid: ~/.openclaw/openclaw.json
The WebSocket connection closes when the script sends a large payload

OpenShell closes the connection on any client WebSocket message over 4 MiB. Split large page.evaluate arguments or page.setContent payloads into smaller ones, or load the content from a URL instead.

Next steps​

Was this page helpful?