Remote Browser Control
Run Chrome on one machine, control it from another.
Server (the machine with the browser)
Section titled “Server (the machine with the browser)”Install vibium (this downloads Chrome + chromedriver automatically):
npm install -g vibiumFind the chromedriver path and start it:
vibium paths$(vibium paths | grep Chromedriver | cut -d' ' -f2) --port=9515 --allowed-ips=""Client (your dev machine)
Section titled “Client (your dev machine)”Install vibium locally — this gives you both the CLI (npx vibium) and the JS library:
npm install vibiumOr install globally for a bare vibium command:
npm install -g vibium# One-liner with env var (simplest)export VIBIUM_CONNECT_URL=ws://your-server:9515/sessionvibium go https://example.comvibium title # "Example Domain"vibium text h1 # "Example Domain"# Or use the start command with a URLvibium start ws://your-server:9515/sessionvibium go https://example.comvibium titlevibium stopBoth 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:
# 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_CAPSexport VIBIUM_CONNECT_CAPS='{"vendor:options":{"someOption":"value"}}'vibium start https://USER:KEY@grid.example.com/wd/hubvibium go https://example.comvibium stop # sends DELETE /session/<id> — releases the cloud slotExtra 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.
MCP Server
Section titled “MCP Server”The MCP server reads the same env vars, so AI agents can use a remote browser:
VIBIUM_CONNECT_URL=ws://your-server:9515/session vibium mcpOr in your Claude Desktop / Claude Code config:
{ "mcpServers": { "vibium": { "command": "vibium", "args": ["mcp"], "env": { "VIBIUM_CONNECT_URL": "ws://your-server:9515/session" } } }}JavaScript
Section titled “JavaScript”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()Python
Section titled “Python”pip install vibiumfrom 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.
jshell
Section titled “jshell”The env-var fallback makes jshell a first-class way to drive a remote
browser interactively — no build file, no StartOptions:
curl -sO https://repo1.maven.org/maven2/com/vibium/vibium/26.11.16/vibium-26.11.16.jarcurl -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.jarjshell> import com.vibium.*jshell> var bro = Vibium.start() // picks up VIBIUM_CONNECT_URLjshell> var page = bro.page()jshell> page.go("https://example.com")jshell> page.title()$4 ==> "Example Domain"jshell> bro.stop()With Authentication
Section titled “With Authentication”If your endpoint requires auth headers (e.g. a cloud browser provider):
CLI / MCP — set VIBIUM_CONNECT_API_KEY to send a Bearer token:
export VIBIUM_CONNECT_URL=wss://cloud.example.com/sessionexport VIBIUM_CONNECT_API_KEY=my-tokenvibium go https://example.comOr 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:
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));Environment Variables
Section titled “Environment Variables”| Variable | Description |
|---|---|
VIBIUM_CONNECT_URL | Remote BiDi WebSocket endpoint (e.g. ws://host:9515/session) |
VIBIUM_CONNECT_API_KEY | Sent as Authorization: Bearer <key> |
VIBIUM_CONNECT_HEADERS | Extra connect headers, one Key: value per line |
VIBIUM_CONNECT_CAPS | Extra 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.
How It Works
Section titled “How It Works”┌────────── 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.