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.
- A Browserless API token from your account dashboard
- OpenShell 0.1.8 or newer with a running gateway.
openshell statusshould showConnected - A sandbox image with Node.js, such as
node:26-trixie-slimfor the quick check. OpenShell's default sandbox image has nonodeorcurl - For the client examples, an image with
puppeteer-core,playwright-coreor@modelcontextprotocol/sdkinstalled. 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
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.yamlResponse:
Imported 1 provider profile.To keep the profile from changing under you, replace
mainin the URL with a commit SHA from the repository.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_TOKENResponse:
✓ Created provider browserlessRun a quick check
Start a throwaway sandbox with the provider attached and fetch example.com through the Browserless
/contentAPI: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.
- Puppeteer
- Playwright
- BrowserQL
- MCP server
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
import { chromium } from 'playwright-core';
const region = process.env.BROWSERLESS_REGION ?? 'production-sfo';
const token = encodeURIComponent(process.env.BROWSERLESS_TOKEN ?? '');
async function title(browser) {
try {
const context = browser.contexts()[0] ?? (await browser.newContext());
const page = await context.newPage();
await page.goto('https://example.com');
return await page.title();
} finally {
await browser.close();
}
}
const overCDP = await chromium.connectOverCDP(`wss://${region}.browserless.io?token=${token}`);
console.log(`playwright (CDP): ${await title(overCDP)}`);
const native = await chromium.connect(`wss://${region}.browserless.io/chromium/playwright?token=${token}`);
console.log(`playwright (native): ${await title(native)}`);
Response:
playwright (CDP): Example Domain
playwright (native): Example Domain
const region = process.env.BROWSERLESS_REGION ?? 'production-sfo';
const token = encodeURIComponent(process.env.BROWSERLESS_TOKEN ?? '');
const res = await fetch(`https://${region}.browserless.io/chromium/bql?token=${token}`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
query: 'mutation { goto(url: "https://example.com") { status } title { title } }',
}),
});
if (!res.ok) throw new Error(`BrowserQL returned ${res.status}`);
const { data } = await res.json();
console.log(`browserql: ${data.goto.status} ${data.title.title}`);
Response:
browserql: 200 Example Domain
Send each BrowserQL request as a single anonymous operation, as above. The profile denies named operations and the reconnect mutation.
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const token = encodeURIComponent(process.env.BROWSERLESS_TOKEN ?? '');
const transport = new StreamableHTTPClientTransport(new URL(`https://mcp.browserless.io/mcp?token=${token}`));
const client = new Client({ name: 'browserless-openshell-example', version: '1.0.0' });
await client.connect(transport);
try {
const { tools } = await client.listTools();
console.log(`mcp: ${tools.length} tools`);
const result = await client.callTool({
name: 'browserless_smartscraper',
arguments: { url: 'https://example.com', formats: ['markdown'] },
});
const text = (result.content ?? []).map((part) => part.text ?? '').join('\n');
console.log(`mcp smartscraper: ${text.includes('Example Domain') ? 'Example Domain found' : text.slice(0, 200)}`);
} finally {
await client.close();
}
Response:
mcp: 23 tools
mcp smartscraper: Example Domain found
The tool count follows the hosted server and changes as tools are added. OpenShell accepts MCP revision 2025-11-25 by default, which current MCP SDKs negotiate.
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) andmcp.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
nodeandcurlat/usr/binor/usr/local/bincan reach those hosts. If your client lives elsewhere, import an edited copy of the profile with your paths inbinaries. - REST: full access, including
DELETEso 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.reconnecthands 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_functionand the two Stripe Link payment tools,browserless_link_checkoutandbrowserless_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.yamlResponse:
✓ Deleted provider profile browserless
Imported 1 provider profile. -
Sandbox images: OpenShell's default filesystem policy blocks reads under
/opt. Install scripts andnode_modulesunder/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.evaluatearguments orpage.setContentpayloads 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.