Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .github/workflows/actions.lock
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
# Docs: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
'.github/workflows/profile-lint.yml':
- 'actions/checkout@v7.0.1'
dependencies:
'actions/checkout@v7.0.1':
ref: 'v7.0.1'
commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1'
owner_id: 44036562
repo_id: 197814629
39 changes: 39 additions & 0 deletions .github/workflows/profile-lint.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
name: Profile lint

on:
pull_request:
push:
branches:
- main
schedule:
# Weekly, the day after OpenShell's usual Tuesday release, so a breaking
# provider change shows up here before users hit it.
- cron: '0 6 * * 3'
workflow_dispatch:

permissions: {}

jobs:
lint:
name: Lint profiles (OpenShell ${{ matrix.openshell }})
# ubuntu-latest ships Docker, which the throwaway gateway uses as its
# compute driver.
runs-on: ubuntu-latest
timeout-minutes: 15
permissions:
contents: read
strategy:
fail-fast: false
matrix:
# latest: what new users install. v0.1.8: the oldest supported release.
openshell: [latest, v0.1.8]

steps:
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false

- name: Lint, import and attach every profile
env:
OPENSHELL_VERSION: ${{ matrix.openshell }}
run: scripts/lint-profiles.sh
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
node_modules/
.DS_Store
*.log
.env
.env.local
1 change: 1 addition & 0 deletions .nvmrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
26
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Changelog

All notable changes to these profiles are documented here. Tags match the headings below.

## 1.0.0 — initial release

- Added `providers/browserless.yaml`: REST, BrowserQL on its own `protocol: graphql` endpoints, as single anonymous operations without `reconnect`, CDP and Playwright WebSockets on their own `protocol: websocket` endpoints (required from OpenShell 0.1.8), the worker-pinned durable-session and reconnect URLs in every region, and the hosted MCP server. The endpoints that run your own code in the browser (`/function`, `/download` and `browserless_function`) and the two Stripe Link MCP tools are denied. One Browserless API token, `BROWSERLESS_TOKEN`, sent as the `token` query parameter everywhere, including the MCP server.
- Added `providers/browserless-linkgated.yaml` and `providers/browserless-link-approve.yaml` for Stripe Link behind human approval.
- Documented NemoClaw's own route to the hosted MCP server.
- Added Puppeteer, Playwright, BrowserQL and MCP examples with a sandbox image.
- Added `scripts/lint-profiles.sh` and a CI workflow that lints and imports every profile and starts a sandbox with each, against the latest OpenShell release and 0.1.8, on pull requests and weekly.
- Requires OpenShell 0.1.8 or newer. Tested on 0.1.8.
142 changes: 142 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
# Browserless for NVIDIA OpenShell and NemoClaw

Give an agent running in an [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandbox a real browser, without installing one in the sandbox.

This repository holds OpenShell **provider profiles** for [Browserless](https://www.browserless.io). 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.

```shell
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](https://www.browserless.io/signup/email) and copy the API token from [account.browserless.io](https://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](https://github.com/browserless/openshell/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:

```shell
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

```shell
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](docs/nemoclaw.md) covers NemoClaw's own route to the hosted MCP server.

---

## Profiles

| Profile | Use it for |
|---|---|
| [`providers/browserless.yaml`](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](#what-these-profiles-allow)). |
| [`providers/browserless-linkgated.yaml`](providers/browserless-linkgated.yaml) | Ordinary browsing, with Stripe Link only after a person approves. See [docs/stripe-link-approval.md](docs/stripe-link-approval.md). |
| [`providers/browserless-link-approve.yaml`](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](docs/stripe-link-approval.md), 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:

```shell
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`](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/](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](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:

```shell
OPENSHELL_VERSION=v0.1.8 scripts/lint-profiles.sh
```

---

## Resources

- OpenShell: [github.com/NVIDIA/OpenShell](https://github.com/NVIDIA/OpenShell) and the [provider docs](https://docs.nvidia.com/openshell/latest/how-it-works/providers/overview)
- NemoClaw: [github.com/NVIDIA/NemoClaw](https://github.com/NVIDIA/NemoClaw)
- Browserless docs: [docs.browserless.io](https://docs.browserless.io)
- Hosted MCP server: [`https://mcp.browserless.io/mcp`](https://mcp.browserless.io/mcp)
- Report a security issue: [SECURITY.md](SECURITY.md)

---

## License

MIT, see [LICENSE](LICENSE).

The Browserless server itself is licensed separately under SSPL-1.0.
24 changes: 24 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# Security Policy

## Reporting a vulnerability

If you discover a security vulnerability in these profiles, the scripts or the examples, please report it privately. **Do not open a public GitHub issue.**

Email: **support@browserless.io**

When reporting, please include:

- A description of the vulnerability and its potential impact
- Steps to reproduce, ideally with a minimal proof of concept
- The affected profile or file, and the OpenShell version you used
- Any suggested mitigation, if known

## Out of scope

The following are generally **not** considered vulnerabilities in this project:

- Issues in OpenShell or NemoClaw themselves. Report those to NVIDIA as their [OpenShell security policy](https://github.com/NVIDIA/OpenShell/blob/main/SECURITY.md) and [NemoClaw security policy](https://github.com/NVIDIA/NemoClaw/blob/main/SECURITY.md) describe.
- Issues in the Browserless API or Chrome itself. Report those to [browserless.io](https://www.browserless.io) directly.
- A profile you edited to allow more than the published one does.

Thanks for helping keep the project and its users safe.
5 changes: 5 additions & 0 deletions assets/logo.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
23 changes: 23 additions & 0 deletions docs/nemoclaw.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# NemoClaw

[NemoClaw](https://github.com/NVIDIA/NemoClaw) runs OpenClaw inside an OpenShell sandbox. It pins an OpenShell release older than 0.1.8, so the provider profiles in this repository do not apply to it. Use NemoClaw's own MCP support instead.

## Hosted MCP server

NemoClaw adds the hosted Browserless MCP server as a tool provider. When you add it, deny the Stripe Link payment tools and `browserless_function`, which runs your own code in the browser:

```shell
export BROWSERLESS_TOKEN=<your Browserless API token>
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
```

NemoClaw stores the token as an OpenShell provider, and the sandbox sees only a placeholder. The agent gets every Browserless MCP tool except the three denied ones, including `browserless_agent` for multi-step browsing and `browserless_smartscraper` for single pages.

Tested with NemoClaw v0.0.142.

## Puppeteer, Playwright and OpenClaw's built-in browser

These connect to Browserless over a WebSocket, and the profiles here need OpenShell 0.1.8 or newer for that. Use them in an OpenShell 0.1.8 sandbox outside NemoClaw, with [`providers/browserless.yaml`](../providers/browserless.yaml), until NemoClaw moves to OpenShell 0.1.8 or newer.
55 changes: 55 additions & 0 deletions docs/stripe-link-approval.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Stripe Link behind human approval

Browserless can pay with a [Stripe Link](https://link.com) wallet. The main profile denies both Stripe Link MCP tools, `browserless_link_checkout` and `browserless_link_connect`, but keeps REST open, and Browserless's own agent endpoints can use a connected wallet. If the account has a connected wallet, or an agent should use the wallet only after a person says yes, use the two profiles below instead. They need OpenShell 0.1.8 or newer and were tested on 0.1.8.

- `providers/browserless-linkgated.yaml` covers ordinary browsing: REST `/content`, BrowserQL on `/chromium/bql` (single anonymous operations, without `reconnect`), `/json/*` discovery, CDP on `/`, and the MCP tools `browserless_smartscraper` and `browserless_usage`. Every Stripe Link REST path is outside it, and `browserless_link_checkout` is always denied.
- `providers/browserless-link-approve.yaml` is credential-free. Attaching it to a sandbox allows `browserless_link_connect`; detaching it takes that away again.

## Set it up

```shell
openshell settings set --global --key agent_policy_proposals_enabled --value true --yes
openshell provider profile import -f providers/browserless-linkgated.yaml --global
openshell provider profile import -f providers/browserless-link-approve.yaml --global

export BROWSERLESS_TOKEN=<your Browserless API token>
openshell provider create --name browserless-gated --type browserless-linkgated \
--credential BROWSERLESS_TOKEN
openshell provider create --name link-approve --type browserless-link-approve

openshell sandbox create --name agent --from <your image> --provider browserless-gated
```

## How approval works

1. **The agent asks.** A Stripe Link REST call such as `GET /integrations/stripe-link/status` gets `403 policy_denied`. The agent proposes a rule for exactly that path by posting to `http://policy.local/v1/proposals` from inside the sandbox.
2. **A person reviews it.** The proposal shows the rule, the endpoint and the agent's reason:

```shell
openshell rule get agent --status pending
openshell rule approve agent --chunk-id <chunk-id>
```

3. **A person allows the wallet tool**, if the agent also needs `browserless_link_connect`:

```shell
openshell sandbox provider attach agent link-approve
```

4. **Revoke it** when the purchase is done:

```shell
openshell sandbox provider detach agent link-approve
```

Detaching removes only the wallet tool. The REST rule approved in step 2 stays in the sandbox's policy.

`browserless_link_checkout` stays denied at every step: approval through OpenShell's policy advisor cannot lift a tool-level deny. Review every proposal before approving it, especially one that opens another Browserless path. Browserless's own agent endpoints can also use a connected Stripe Link wallet.

## What we observed on 0.1.8

| Step | REST link status | `browserless_link_connect` | `browserless_link_checkout` | `browserless_smartscraper` |
|---|---|---|---|---|
| Before approval | 403 `policy_denied` | denied | denied | works |
| After approving the rule and attaching `link-approve` | 200 | works | denied | works |
| After detaching `link-approve` | 200 (the approved rule stays) | denied | denied | works |
Loading
Loading