Skip to content

Remote Browser Control

Run Chrome on one machine, control it from another.


Install vibium (this downloads Chrome + chromedriver automatically):

Terminal window
npm install -g vibium

Find the chromedriver path and start it:

/Users/you/.cache/vibium/.../chromedriver
vibium paths
$(vibium paths | grep Chromedriver | cut -d' ' -f2) --port=9515 --allowed-ips=""

Install vibium locally — this gives you both the CLI (npx vibium) and the JS library:

Terminal window
npm install vibium

Or install globally for a bare vibium command:

Terminal window
npm install -g vibium
Terminal window
# One-liner with env var (simplest)
export VIBIUM_CONNECT_URL=ws://your-server:9515/session
vibium go https://example.com
vibium title # "Example Domain"
vibium text h1 # "Example Domain"
Terminal window
# Or use the start command with a URL
vibium start ws://your-server:9515/session
vibium go https://example.com
vibium title
vibium stop

Both endpoint shapes work: a browser-level URL like ws://host:9515/session (vibium creates the session) and a URL for a session that already exists, such as a chromedriver webSocketUrl or a Selenium Grid ws://host:4444/session/<id>/se/bidi (vibium attaches to it).

Classic WebDriver endpoints (Selenium Grid, cloud grids)

Section titled “Classic WebDriver endpoints (Selenium Grid, cloud grids)”

An http:// or https:// URL is treated as a classic WebDriver endpoint. vibium creates a session there with webSocketUrl: true and connects to the BiDi URL the endpoint returns — one URL drives a local Selenium Grid or a hosted grid cloud:

Terminal window
# Self-hosted Selenium Grid (or docker selenium standalone-chrome).
# Verified against selenium-server 4.46.0 standalone: vibium creates the
# session, attaches to the returned /se/bidi socket, and the slot is
# released on stop.
vibium start http://localhost:4444
# Cloud grid: credentials go in the URL (sent as Basic auth),
# vendor options in VIBIUM_CONNECT_CAPS
export VIBIUM_CONNECT_CAPS='{"vendor:options":{"someOption":"value"}}'
vibium start https://USER:KEY@grid.example.com/wd/hub
vibium go https://example.com
vibium stop # sends DELETE /session/<id> — releases the cloud slot

Extra alwaysMatch capabilities come from VIBIUM_CONNECT_CAPS (a JSON object), the --connect-caps flag on vibium daemon start / vibium pipe, or the caps option in the JS/Python/Java clients. webSocketUrl: true is always added for you. If the endpoint does not return a webSocketUrl, the remote end does not support WebDriver BiDi, and vibium says so instead of leaving the session running.

The MCP server reads the same env vars, so AI agents can use a remote browser:

Terminal window
VIBIUM_CONNECT_URL=ws://your-server:9515/session vibium mcp

Or in your Claude Desktop / Claude Code config:

{
"mcpServers": {
"vibium": {
"command": "vibium",
"args": ["mcp"],
"env": {
"VIBIUM_CONNECT_URL": "ws://your-server:9515/session"
}
}
}
}
import { browser } from 'vibium'
const bro = await browser.start('ws://your-server:9515/session')
const page = await bro.page()
await page.go('https://example.com')
console.log(await page.title()) // "Example Domain"
console.log(await page.find({ css: 'h1' }).text()) // "Example Domain"
await bro.stop()

Sync API:

const { browser } = require('vibium/sync')
const bro = browser.start('ws://your-server:9515/session')
const page = bro.page()
page.go('https://example.com')
console.log(page.title()) // "Example Domain"
console.log(page.find({ css: 'h1' }).text()) // "Example Domain"
bro.stop()
Terminal window
pip install vibium
from vibium.async_api import browser
bro = await browser.start("ws://your-server:9515/session")
page = await bro.page()
await page.go("https://example.com")
print(await page.title()) # "Example Domain"
print(await (await page.find(css="h1")).text()) # "Example Domain"
await bro.stop()

Sync API:

from vibium.sync_api import browser
bro = browser.start("ws://your-server:9515/session")
page = bro.page()
page.go("https://example.com")
print(page.title()) # "Example Domain"
print(page.find(css="h1").text()) # "Example Domain"
bro.stop()
implementation 'com.vibium:vibium:26.11.16'
import com.vibium.Vibium;
import com.vibium.Browser;
import com.vibium.Page;
import com.vibium.types.StartOptions;
Browser bro = Vibium.start(new StartOptions()
.connectURL("ws://your-server:9515/session"));
Page page = bro.page();
page.go("https://example.com");
System.out.println(page.title()); // "Example Domain"
bro.stop();

VIBIUM_CONNECT_URL and VIBIUM_CONNECT_API_KEY work here too — Vibium.start() with no options picks them up.

The env-var fallback makes jshell a first-class way to drive a remote browser interactively — no build file, no StartOptions:

Terminal window
curl -sO https://repo1.maven.org/maven2/com/vibium/vibium/26.11.16/vibium-26.11.16.jar
curl -sO https://repo1.maven.org/maven2/com/google/code/gson/gson/2.11.0/gson-2.11.0.jar
VIBIUM_CONNECT_URL=ws://your-server:9515/session \
jshell --class-path vibium-26.11.16.jar:gson-2.11.0.jar
jshell> import com.vibium.*
jshell> var bro = Vibium.start() // picks up VIBIUM_CONNECT_URL
jshell> var page = bro.page()
jshell> page.go("https://example.com")
jshell> page.title()
$4 ==> "Example Domain"
jshell> bro.stop()

If your endpoint requires auth headers (e.g. a cloud browser provider):

CLI / MCP — set VIBIUM_CONNECT_API_KEY to send a Bearer token:

Terminal window
export VIBIUM_CONNECT_URL=wss://cloud.example.com/session
export VIBIUM_CONNECT_API_KEY=my-token
vibium go https://example.com

Or pass headers explicitly with the daemon. A flag value is visible to other users in the process list, so prefer VIBIUM_CONNECT_HEADERS for secrets:

Terminal window
vibium daemon start --connect wss://cloud.example.com/session \
--connect-header "Authorization: Bearer my-token"

JavaScript:

const bro = await browser.start('wss://cloud.example.com/bidi', {
headers: { 'Authorization': 'Bearer my-token' }
})

Sync:

const bro = browser.start('wss://cloud.example.com/bidi', {
headers: { 'Authorization': 'Bearer my-token' }
})

Python:

bro = await browser.start("wss://cloud.example.com/bidi", headers={
"Authorization": "Bearer my-token",
})

Sync:

bro = browser.start("wss://cloud.example.com/bidi", headers={
"Authorization": "Bearer my-token",
})

Java:

Map<String, String> headers = new HashMap<>();
headers.put("Authorization", "Bearer my-token");
Browser bro = Vibium.start(new StartOptions()
.connectURL("wss://cloud.example.com/bidi")
.connectHeaders(headers));

VariableDescription
VIBIUM_CONNECT_URLRemote BiDi WebSocket endpoint (e.g. ws://host:9515/session)
VIBIUM_CONNECT_API_KEYSent as Authorization: Bearer <key>
VIBIUM_CONNECT_HEADERSExtra connect headers, one Key: value per line
VIBIUM_CONNECT_CAPSExtra alwaysMatch capabilities for classic WebDriver endpoints (a JSON object)

These work everywhere — CLI commands, daemon auto-start, the MCP server, and the JS, Python, and Java client libraries.


┌────────── Your Machine ──────────┐ ┌──── Remote Machine ─────┐
│ │ │ │
│ ┌──────────┐ ┌──────────┐ │ WebSocket │ ┌─────────────┐ │
│ │ your code│◄──►│ vibium │◄───┼──────────────┼───►│ chromedriver│ │
│ └──────────┘ └──────────┘ │ │ └──────┬──────┘ │
│ │ │ │ │
│ │ │ ┌──────▼──────┐ │
│ │ │ │ Chrome │ │
│ │ │ └─────────────┘ │
└──────────────────────────────────┘ └─────────────────────────┘

Your code talks to a local vibium process, which proxies to the remote chromedriver over WebSocket. The transport between your code and vibium depends on the interface: IPC for CLI, stdin/stdout pipes for JS/Python clients.

All vibium features (auto-wait, screenshots, tracing) work over remote connections.