Operating System

Browser

Let agents read and search the web from an agentOS VM using Browserbase's cloud browser through the browse CLI — no local browser or sandbox required.

Agents can read and search the web with the Browserbase browse CLI. The page loads in a real browser in Browserbase’s cloud and comes back as clean content — the VM never runs a browser.

Setup

Create a Browserbase account

Sign up and grab your API key and project id from the dashboard:
export BROWSERBASE_API_KEY=bb_... export BROWSERBASE_PROJECT_ID=...

Install

npm install @rivet-dev/agentos @agentos-software/pi @agentos-software/browserbase

Add browse to the VM

import browserbase from "@agentos-software/browserbase";
import pi from "@agentos-software/pi";
import { agentOS, setup } from "@rivet-dev/agentos";

// `browse` is exposed inside the VM as a command on `$PATH`.
const vm = agentOS({
	software: [pi, browserbase],
});

export const registry = setup({ use: { vm } });
registry.start();

Mount the browse CLI skill into the agent’s skills directory so it reaches for browse unprompted (copy the skill folder from the example):

import browserbase from "@agentos-software/browserbase";
import pi from "@agentos-software/pi";
import { agentOS, setup } from "@rivet-dev/agentos";

// Mount the local `skills/` folder into Pi's skills directory
// (`~/.pi/agent/skills`) so the agent can discover the `browse` CLI skill.
const skillsDir = new URL("./skills", import.meta.url).pathname;

const vm = agentOS({
	software: [pi, browserbase],
	mounts: [
		{
			path: "/home/agentos/.pi/agent/skills",
			plugin: { id: "host_dir", config: { hostPath: skillsDir } },
			readOnly: true,
		},
	],
});

export const registry = setup({ use: { vm } });
registry.start();

import browserbase from "@agentos-software/browserbase";
import claude from "@agentos-software/claude-code";
import { agentOS, setup } from "@rivet-dev/agentos";

// Install the `browse` CLI alongside the Claude Code agent. Because `browse`
// reaches the web through the Browserbase cloud, no local browser or sandbox is
// needed — `browse` is exposed inside the VM as a command on `$PATH`.
//
// Mount the local `skills/` folder into Claude Code's skills directory
// (`~/.claude/skills`) so the agent discovers Browserbase's `browse` CLI skill
// and reaches for it on its own, without being told to in the prompt.
const skillsDir = new URL("./skills", import.meta.url).pathname;

const vm = agentOS({
	software: [claude, browserbase],
	mounts: [
		{
			path: "/home/agentos/.claude/skills",
			plugin: { id: "host_dir", config: { hostPath: skillsDir } },
			readOnly: true,
		},
	],
});

export const registry = setup({ use: { vm } });
registry.start();

Use it

import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server-minimal";

const client = createClient<typeof registry>({
	endpoint: "http://localhost:6420",
});
const agent = client.vm.getOrCreate("my-agent");

// The Browserbase credentials go into the session environment, so every
// command the agent runs — including `browse` — inherits them.
const sessionId = await agent.createSession("pi", {
	env: {
		BROWSERBASE_API_KEY: process.env.BROWSERBASE_API_KEY!,
		BROWSERBASE_PROJECT_ID: process.env.BROWSERBASE_PROJECT_ID!,
		ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY!,
	},
});

const response = await agent.sendPrompt(
	sessionId,
	"Run `browse cloud fetch https://example.com` and tell me in one sentence what the page is about.",
);
console.log(response.text);

await agent.closeSession(sessionId);

import { createClient } from "@rivet-dev/agentos/client";
import type { registry } from "./server-minimal";

const client = createClient<typeof registry>({
	endpoint: "http://localhost:6420",
});
const agent = client.vm.getOrCreate("my-agent");

// Drive `browse` directly through the VM's process API. `browse cloud fetch`
// retrieves a page through the Browserbase cloud and returns it as JSON with the
// page rendered as markdown. `browse` reads its credentials from the command
// environment, which we pass through `exec`.
const env = {
	BROWSERBASE_API_KEY: process.env.BROWSERBASE_API_KEY!,
	BROWSERBASE_PROJECT_ID: process.env.BROWSERBASE_PROJECT_ID!,
};

const { stdout } = await agent.exec("browse cloud fetch https://example.com", {
	env,
});

const page = JSON.parse(stdout) as { statusCode: number; content: string };
console.log(`fetched status ${page.statusCode}`);
console.log(page.content);

Command reference

browse cloud fetch https://example.com   # retrieve a page as markdown
browse cloud search "web scraping tools" # search the web
browse cloud sessions list               # list cloud browser sessions
browse cloud projects list               # list Browserbase projects

The interactive driver mode (browse open, browse click, …) is not supported inside the VM yet (#1631). For interactive automation, run browse inside a sandbox via Sandbox Mounting.