Remote Browser

Remote Browser is a cloud Chromium runtime for AI agents, automation scripts, and browser testing workflows. It serves the browser as an API: create real Chromium sessions in the cloud, connect through CDP / WebSocket, run with Stealth Mode for harder-to-detect automation, watch execution through Live Viewer, and keep cookies, login state, and browser history in reusable Profiles.

This repository documents public integration flows and examples for Remote Browser. The product console and backend service are closed source; registration, API keys, browser sessions, Profiles, recordings, and billing are managed inside the Remote Browser App.

• Website: https://remote-browser.dev
• App console: https://app.remote-browser.dev
• Default API service: https://brapi.remote-browser.dev

What It Is For

• Give Hermes, OpenClaw, Codex, Claude, and other agents a reusable cloud browser.
• Connect Playwright / CDP clients to remote Chromium instead of launching a local browser.
• Run browser automation with Stealth Mode, including hardened browser fingerprints and proxy-ready egress.
• Reuse Profiles across automation runs so agents do not need to log in every time.
• Watch tasks through Live Viewer and review runs through recordings.
• Stop idle browsers automatically to avoid wasted runtime.

Stealth Mode

Remote Browser is built for real-world agent browsing, where sites often react differently to local headless browsers, default automation fingerprints, or unstable network identities. Stealth Mode gives your agents a more production-ready browser surface while keeping the integration simple:

• Real cloud Chromium sessions instead of lightweight HTML fetchers or mock browser environments.
• Hardened browser fingerprints for canvas, WebGL, audio, fonts, TLS, and timing-sensitive checks.
• Persistent Profiles so cookies, login state, and browsing context survive across runs.
• Proxy-ready egress for regional routing and network identity control.
• CDP compatibility, so existing Playwright, Hermes, OpenClaw, Codex, Claude, and browser-use style clients can connect without a custom browser driver.

Use Stealth Mode for legitimate automation, QA, agent workflows, and owned-account tasks where reliability matters and the browser should look and behave like a real user-controlled Chromium session.

Quick Start

1. Open https://app.remote-browser.dev, sign up, and log in.
2. Go to API Keys and create an API key with browsers:write. The recommended default scopes are browsers:write, browsers:read, and profiles:read.
3. Go to Remote Browsers. You can click + New Browser to create a browser manually, or let an integration create one automatically through /connect.
4. Open the Integration panel from Remote Browsers or from a browser detail page, choose Hermes Agent, OpenClaw, or Codex / Claude, and copy the command or environment value generated by the App.

Treat API keys as secrets. Do not commit them to source code, logs, screenshots, or public issues.

Hermes Agent

The Remote Browser App generates a Hermes plugin installer. The command installs the browser/remote_browser plugin and sets Hermes browser.cloud_provider to remote_browser.

curl -fsSL https://app.remote-browser.dev/hermes/install.sh | bash -s -- https://app.remote-browser.dev YOUR_API_KEY

The installer writes to:

• ~/.hermes/plugins/browser/remote_browser
• ~/.hermes/config.yaml
• ~/.hermes/.env

After installation, ask Hermes to use the cloud browser:

Open https://google.com and type hello world then tell me the result.

The Hermes plugin uses your API key to create a Remote Browser, polls until the browser is running, then returns the CDP URL to Hermes. When the task is done, the plugin calls the terminate endpoint to close the session.

Optional environment variables:

REMOTE_BROWSER_API_KEY=rb_...
REMOTE_BROWSER_BASE_URL=https://brapi.remote-browser.dev
REMOTE_BROWSER_PROFILE_NAME="Personal Profile"
REMOTE_BROWSER_TIMEOUT_MINUTES=5
REMOTE_BROWSER_RESOLUTION=2560x1440
REMOTE_BROWSER_REGION=auto
REMOTE_BROWSER_RECORDING=true

OpenClaw

The Remote Browser App generates an OpenClaw browser profile installer. The command updates ~/.openclaw/openclaw.json and creates a remote CDP profile named remote-browser.

curl -fsSL https://app.remote-browser.dev/openclaw/install.sh | bash -s -- https://app.remote-browser.dev YOUR_API_KEY

After installation, use Remote Browser through OpenClaw browser commands:

openclaw browser open https://example.com

The OpenClaw profile uses a CDP endpoint like:

wss://brapi.remote-browser.dev/connect?apiKey=YOUR_API_KEY&timeout=5

/connect creates a cloud browser when needed and reuses the default or specified Profile.

Codex / Claude / Playwright

Any CDP-capable tool can connect directly to Remote Browser through the /connect WebSocket URL:

export REMOTE_BROWSER_CDP_URL="wss://brapi.remote-browser.dev/connect?apiKey=YOUR_API_KEY&profileName=Personal%20Profile&timeout=5"

Playwright example:

import { chromium } from "playwright";

const cdpUrl = process.env.REMOTE_BROWSER_CDP_URL;
if (!cdpUrl) {
  throw new Error("REMOTE_BROWSER_CDP_URL is required");
}

const browser = await chromium.connectOverCDP(cdpUrl);
const context = browser.contexts()[0] ?? await browser.newContext();
const page = context.pages()[0] ?? await context.newPage();

await page.goto("https://example.com");
console.log(await page.title());

await browser.close();

Common /connect parameters:

• apiKey: Required. Must include the browsers:write scope.
• profileName: Optional. Selects or creates a Profile, such as Personal Profile.
• timeout: Optional. Idle timeout in minutes, such as 5.
• resolution: Optional. Examples: 2560x1440, 1920x1080.
• region: Optional. Examples: auto, us-east, us-west, asia.
• recording: Optional. Enabled by default.
• proxyType / proxyUrl: Optional. Route the browser through an approved proxy path when configured for your workspace.

Manual Browser Creation

If you want to verify the browser status in the App before connecting:

1. Open https://app.remote-browser.dev.
2. Go to Remote Browsers and click + New Browser.
3. Choose the resolution, idle timeout, region, Profile, and recording retention.
4. Open the browser detail page and click Copy CDP URL.
5. Pass the copied CDP URL to Playwright, an agent, or another CDP client.

You can also click Open Live Viewer to watch the browser while it runs. When the task is finished, click Terminate to stop the browser.

REST API Examples

Create a browser:

curl -X POST "https://brapi.remote-browser.dev/dashboard/remote-browsers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution": "2560x1440",
    "idleTimeoutSeconds": 300,
    "region": "auto",
    "recordingEnabled": true,
    "recordingRetentionDays": 7,
    "launchArguments": ["--disable-dev-shm-usage"]
  }'

Check status:

curl "https://brapi.remote-browser.dev/dashboard/remote-browsers/BROWSER_DISPLAY_ID/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Key: YOUR_API_KEY"

Terminate a browser:

curl -X POST "https://brapi.remote-browser.dev/dashboard/remote-browsers/BROWSER_DISPLAY_ID/terminate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-API-Key: YOUR_API_KEY"

Using The App

• Sign up and log in: open https://app.remote-browser.dev.
• Create an API key: go to API Keys, click + Create API Key, and select browsers:write.
• Create a Profile: go to Profiles and create a browser Profile to preserve login state.
• Create a browser: go to Remote Browsers and click + New Browser.
• Find integration commands: open the Integration panel from the Remote Browsers list or an individual browser page.
• Choose an agent: click Hermes Agent, OpenClaw, or Codex / Claude, then copy the command generated by the App.

Security Notes

• Do not expose API keys or full CDP URLs in code, logs, CI output, or public issues.
• Create separate API keys for different agents so they can be revoked independently.
• Set a reasonable timeout for long-running tasks to avoid idle browser runtime.
• Terminate browsers when work is complete. If you forget, Remote Browser stops them automatically after the idle timeout.