Give an agent running in an NVIDIA OpenShell sandbox a real browser, without installing one in the sandbox.
This repository holds OpenShell provider profiles for Browserless. A provider profile tells OpenShell where a credential may be sent. Your Browserless API token stays in the OpenShell gateway: the sandbox's environment holds a placeholder, and OpenShell puts the real token on requests to Browserless only.
Needs OpenShell 0.1.8 or newer.
openshell provider profile import --global \
--url https://raw.githubusercontent.com/browserless/openshell/main/providers/browserless.yaml
export BROWSERLESS_TOKEN=<your Browserless API token>
openshell provider create --name browserless --type browserless \
--credential BROWSERLESS_TOKENThen attach the provider to a sandbox with --provider browserless. Inside the sandbox, BROWSERLESS_TOKEN holds a placeholder, not the token.
No account yet? Sign up at browserless.io/signup/email and copy the API token from account.browserless.io.
To keep the profile from changing under you, replace main in the URL with a tag from this repository's releases.
Importing a profile that already exists fails. To move to a newer version, delete the profile 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.yamlopenshell provider profile lint -f providers/browserless.yaml
openshell provider profile import -f providers/browserless.yaml --globalNemoClaw pins an older OpenShell release, which these profiles do not support. docs/nemoclaw.md covers NemoClaw's own route to the hosted MCP server.
| Profile | Use it for |
|---|---|
providers/browserless.yaml |
REST, BrowserQL, Puppeteer and Playwright (CDP and native), durable sessions in every region, and the hosted MCP server. The endpoints that run your own code in the browser, browserless_function and the two Stripe Link MCP tools are denied; the rest of REST stays open (see what it allows). |
providers/browserless-linkgated.yaml |
Ordinary browsing, with Stripe Link only after a person approves. See docs/stripe-link-approval.md. |
providers/browserless-link-approve.yaml |
Credential-free companion an operator attaches to allow browserless_link_connect, and detaches to revoke. |
The main profile, providers/browserless.yaml:
- One token, one placement.
BROWSERLESS_TOKENresolves only as thetokenquery parameter, for the REST and WebSocket APIs and for the MCP server (https://mcp.browserless.io/mcp?token=…). - Only Browserless hosts. The token is sent only to
production-*.browserless.io(the SFO, LON and AMS regions) and tomcp.browserless.io/mcp. Requests from the sandbox to any other host are blocked by the sandbox's network policy. - Only the processes you list.
binariesletsnodeandcurlat/usr/binor/usr/local/binreach those hosts. Edit it to match your image. - REST with full access, including
DELETEso an agent can stop its own sessions, except the endpoints that run your own code in the browser. Any path that ends in/functionor/download, in any browser or region form, getspolicy_denied; that includes/profile/<name>/download. So does/config, the server configuration endpoint. - BrowserQL: every query and mutation except
reconnect, which hands the live browser to another client. Send each request as a single anonymous operation (mutation { … }); named operations are denied. To keep a browser between connections, use a durable session (POST /session) and the connect and BrowserQL URLs it returns. - WebSockets only on the CDP and Playwright connect paths, and on the worker-pinned session and reconnect URLs that the API returns.
- Every MCP tool except
browserless_functionand the two Stripe Link tools. OpenShell answersbrowserless_function,browserless_link_checkoutandbrowserless_link_connectwithpolicy_denied. The Stripe Link rules cover the MCP tools only. REST stays open, including Browserless's own agent endpoints, which can use a Stripe Link wallet connected to the account. If the account has a connected wallet, use the Link-gated profiles, whose REST access is an allow-list.
Usage is billed to the Browserless account that owns the token, as it is outside OpenShell.
This starts a throwaway sandbox and fetches example.com through Browserless. OpenShell's default sandbox image has no curl or node, so it uses the official Node image:
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: ${process.env.BROWSERLESS_TOKEN} is read inside the sandbox, where it holds the placeholder. scripts/smoke.sh runs the same check and prints PASS or FAIL.
Puppeteer, Playwright, BrowserQL and MCP examples, with an image to run them in, are in examples/.
- OpenShell 0.1.8 and newer need WebSocket paths on their own
protocol: websocketendpoints, and resolve each credential only where the profile places it. The main profile does both. - Earlier OpenShell releases are not supported.
- OpenShell closes the connection on any client WebSocket message over 4 MiB.
- OpenShell accepts MCP revision
2025-11-25by default; older MCP clients getmcp_protocol_version_not_allowed.
Details, and what each profile was tested on: docs/version-notes.md.
providers/ OpenShell provider profiles
docs/ Version notes, NemoClaw's MCP route, Stripe Link approval
examples/ Puppeteer, Playwright, BrowserQL and MCP clients, and a sandbox image
scripts/lint-profiles.sh Lints, imports and attaches every profile on a throwaway gateway (CI)
scripts/smoke.sh The quick check above
assets/logo.svg Browserless logo
CI runs scripts/lint-profiles.sh against the latest OpenShell release and against 0.1.8 on every pull request and once a week. It runs on Linux with Docker and a kernel with Landlock; locally:
OPENSHELL_VERSION=v0.1.8 scripts/lint-profiles.sh- OpenShell: github.com/NVIDIA/OpenShell and the provider docs
- NemoClaw: github.com/NVIDIA/NemoClaw
- Browserless docs: docs.browserless.io
- Hosted MCP server:
https://mcp.browserless.io/mcp - Report a security issue: SECURITY.md
MIT, see LICENSE.
The Browserless server itself is licensed separately under SSPL-1.0.