Skip to content
browserlessPublic

About

Browserless provider profiles for NVIDIA OpenShell and NemoClaw

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

Repository files navigation

Browserless for NVIDIA OpenShell and NemoClaw

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.


Install

Import from this repository (recommended)

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_TOKEN

Then 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.

Pin a version

To keep the profile from changing under you, replace main in the URL with a tag from this repository's releases.

Update

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.yaml

From a local copy

openshell provider profile lint   -f providers/browserless.yaml
openshell provider profile import -f providers/browserless.yaml --global

NemoClaw pins an older OpenShell release, which these profiles do not support. docs/nemoclaw.md covers NemoClaw's own route to the hosted MCP server.


Profiles

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.

What these profiles allow

The main profile, providers/browserless.yaml:

  • One token, one placement. BROWSERLESS_TOKEN resolves only as the token query 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 to mcp.browserless.io/mcp. Requests from the sandbox to any other host are blocked by the sandbox's network policy.
  • Only the processes you list. binaries lets node and curl at /usr/bin or /usr/local/bin reach those hosts. Edit it to match your image.
  • REST with full access, including DELETE so an agent can stop its own sessions, except the endpoints that run your own code in the browser. Any path that ends in /function or /download, in any browser or region form, gets policy_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_function and the two Stripe Link tools. OpenShell answers browserless_function, browserless_link_checkout and browserless_link_connect with policy_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.


Quick check

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/.


Version notes

  • OpenShell 0.1.8 and newer need WebSocket paths on their own protocol: websocket endpoints, 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-25 by default; older MCP clients get mcp_protocol_version_not_allowed.

Details, and what each profile was tested on: docs/version-notes.md.


Repository layout

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

Resources


License

MIT, see LICENSE.

The Browserless server itself is licensed separately under SSPL-1.0.

About

Browserless provider profiles for NVIDIA OpenShell and NemoClaw

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages