Skip to content

feat: add Browserless provider profiles for NVIDIA OpenShell - #1

Merged
Xrazik1 merged 7 commits into
mainfrom
feat/provider-profiles
Nov 16, 2026
Merged

Xrazik1 merged 7 commits into
mainfrom
feat/provider-profiles

Conversation

@Xrazik1

@Xrazik1 Xrazik1 commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

What this adds

Provider profiles that let an agent in an NVIDIA OpenShell sandbox use Browserless. The Browserless API token stays in the OpenShell gateway; the sandbox's environment holds a placeholder. One credential, BROWSERLESS_TOKEN, sent as the token query parameter to every Browserless endpoint, including the hosted MCP server. Requires OpenShell 0.1.8 or newer.

  • 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 (/function, /download and browserless_function), the server configuration endpoint (/config) and the two Stripe Link MCP tools are denied. The rest of REST stays open, so the docs point accounts with a connected Stripe Link wallet to the Link-gated profiles.
    • BrowserQL runs through protocol: graphql endpoints that take one anonymous operation per request and allow every query and mutation except reconnect. Durable sessions cover keeping a browser between connections.
    • WebSockets are allowed only on the CDP and Playwright connect paths and on the worker-pinned session and reconnect URLs the API returns, each on its own protocol: websocket endpoint, as OpenShell 0.1.8 requires. Upgrades to BrowserQL paths are refused.
  • providers/browserless-linkgated.yaml and providers/browserless-link-approve.yaml: Stripe Link behind human approval.
  • examples/: Puppeteer, Playwright, BrowserQL and MCP clients, with a sandbox image.
  • scripts/lint-profiles.sh and the Profile lint workflow: lint and import every profile, then start a sandbox with a provider built from each and wait for the gateway to accept its policy. Runs against the latest OpenShell release and 0.1.8, on pull requests, on pushes to main, and weekly.
  • docs/: version notes, NemoClaw's own route to the hosted MCP server, and the Stripe Link approval flow.
  • README, CHANGELOG and SECURITY, laid out like browserless/cursor-mcp-plugin.

How it was tested

On OpenShell 0.1.8, the latest release, with the macOS VM driver and a real Browserless account:

  • Every command block in README.md, examples/README.md and docs/stripe-link-approval.md, run as written.
  • Examples: Puppeteer, Playwright over CDP and native, BrowserQL and MCP (browserless_smartscraper, connected with ?token=) all return example.com on Node 26 (node:26-trixie-slim), with the Docker and macOS VM drivers. LON and AMS were checked with the Docker driver.
  • Durable sessions: create, connect through the worker-pinned URL, run BrowserQL on the session URL, and stop. CDP reconnect URLs (Browserless.reconnect) re-attach on / and /chromium/stealth.
  • Boundaries: requests to hosts outside the profile are blocked; /function, /download and /config in every browser, pinned and prefixed form, browserless_function, browserless_link_checkout and browserless_link_connect get policy_denied; WebSockets on undeclared paths are refused, and a client WebSocket message over 4 MiB closes the connection.
  • BrowserQL rule: reconnect gets policy_denied on every BrowserQL path shape tried, over HTTP and WebSocket. That covers bare, with an id, durable-session, worker-pinned and prefixed paths; path variations such as case, slashes, dot segments and encoding; and query forms such as aliases, fragments, operation selection, GET, raw GraphQL and batched bodies. Named operations get policy_denied. Ordinary anonymous BrowserQL queries keep working, including on durable-session URLs.
  • Link-gated profile: /json/version discovery works, BrowserQL follows the same rule, and Stripe Link REST paths stay denied until approved.
  • Stripe Link approval: denied before approval, allowed after approving the rule and attaching link-approve, and browserless_link_connect denied again after detaching. browserless_link_checkout stays denied throughout. Read-only calls only.
  • scripts/lint-profiles.sh against the latest release and 0.1.8 on a Linux Docker host with Landlock, plus negative controls: a profile that fails lint, and one that lints and imports but whose policy the gateway rejects when a sandbox starts, both exit 1. shellcheck and actionlint are clean.
  • The NemoClaw MCP command was tested with NemoClaw v0.0.142 and re-checked against NemoClaw's current docs.

After merge

  • Tag v1.0.0, so users can pin the import URL as the README describes.

🤖 Generated with Claude Code

Xrazik1 and others added 2 commits November 13, 2026 18:56
Provider profiles that let an agent in an NVIDIA OpenShell sandbox
(0.1.8 or newer) use Browserless: REST, BrowserQL, Puppeteer,
Playwright, durable sessions and the hosted MCP server. The API token
stays in the OpenShell gateway.

- providers/: the main profile, with WebSocket paths on their own
  endpoints, and a Stripe Link approval pair.
- examples/: Puppeteer, Playwright, BrowserQL and MCP clients with a
  sandbox image.
- scripts/ and CI: lint and import every profile against the latest
  OpenShell release and 0.1.8, on pull requests and weekly.
- docs/: version notes, NemoClaw's hosted MCP route and the Stripe Link
  approval flow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
BrowserQL paths, including the worker-pinned durable-session URLs, now
use protocol: graphql endpoints. Each request must be a single anonymous
operation, and every query and mutation is allowed except reconnect,
which hands the live browser to another client. Agents keep a browser
between connections with durable sessions instead. The Link-gated
profile gets the same rule on /chromium/bql.

WebSocket upgrades are limited to the CDP and Playwright connect paths
and the worker-pinned session and reconnect URLs the API returns; the
unpinned reconnect and session-connect prefixes are dropped, and
upgrades to BrowserQL paths are refused. The Link-gated profile's
discovery rules match single-segment /json/* paths, with or without a
trailing slash.

scripts/lint-profiles.sh now also starts a sandbox with a provider built
from each profile and waits for the gateway to accept its policy, which
catches rules that lint and import but are rejected when a sandbox
starts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Xrazik1
Xrazik1 marked this pull request as ready for review November 13, 2026 20:59
Xrazik1 and others added 2 commits November 13, 2026 22:11
…er curl

The main profile denies the two Stripe Link MCP tools, while its REST
access stays open, including Browserless's own agent endpoints, which
can use a Stripe Link wallet connected to the account. Say so in the
profile, README and approval doc, and point accounts with a connected
wallet to the Link-gated profiles.

browserless-link-approve.yaml now lists the same node and curl binaries
as the Link-gated profile, so attaching it allows browserless_link_connect
for either client.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
BROWSERLESS_TOKEN is now the only credential. It is sent as the token
query parameter to every endpoint, including the hosted MCP server
(https://mcp.browserless.io/mcp?token=...). The README, the Link docs
and the MCP example drop BROWSERLESS_MCP_TOKEN.

The main profile denies the endpoints that run your own code in the
browser. That covers any path ending in /function or /download on the
regional hosts, in its bare, per-browser and worker-pinned forms, with or
without a trailing slash; it also covers /profile/<name>/download. It
denies the browserless_function MCP tool as well. The NemoClaw doc
denies browserless_function too.

lint-profiles.sh silences SC2329 next to SC2317 for the trap-called
cleanup function.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@devin-ai-integration devin-ai-integration Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

Xrazik1 and others added 2 commits November 14, 2026 01:36
The main profile also denies /config, the server configuration endpoint,
in its bare, trailing-slash and prefixed forms, so the profile does not
depend on the hosted service keeping that route disabled.

The README and version notes say that OpenShell accepts MCP revision
2025-11-25 by default, so an older MCP client gets
mcp_protocol_version_not_allowed, and point to the mcp.versions setting.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The main profile's header now lists /config next to /function and
/download among the blocked REST endpoints. The comment above the REST
deny rules says they cover every path on these hosts that the endpoint
handles, and that no WebSocket endpoint overlaps those paths.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The examples image now builds FROM node:26-trixie-slim and .nvmrc is 26.
The README quick check, scripts/smoke.sh, the profile's smoke-test
comment, the version notes and the lint script's sandbox image use
node:26-trixie-slim too, so every documented command runs on the same
image.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Xrazik1
Xrazik1 merged commit 98bf3aa into main Nov 16, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants