Extensions

Browser Automation

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

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.
await agent.sessions.open({
	agent: "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.sessions.prompt({
	content: [
		{
			type: "text",
			text: "Run `browse cloud fetch https://example.com` and tell me in one sentence what the page is about.",
		},
	],
});
console.log(response.message?.content ?? []);

await agent.sessions.delete();

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.process.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 an external sandbox via External Sandboxes.

Embedded API

Install the same Browserbase software package and pass its credentials through the embedded session environment.

import browserbase from "@agentos-software/browserbase";
import pi from "@agentos-software/pi";
import { AgentOs } from "@rivet-dev/agentos-core";

const { ANTHROPIC_API_KEY, BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID } =
	process.env;
if (!ANTHROPIC_API_KEY || !BROWSERBASE_API_KEY || !BROWSERBASE_PROJECT_ID) {
	throw new Error("Set the Anthropic and Browserbase environment variables.");
}

const vm = await AgentOs.create({ software: [pi, browserbase] });

try {
	await vm.sessions.open({
		agent: "pi",
		env: {
			ANTHROPIC_API_KEY,
			BROWSERBASE_API_KEY,
			BROWSERBASE_PROJECT_ID,
		},
	});
	await vm.sessions.prompt({
		content: [
			{
				type: "text",
				text: "Use browse to summarize https://example.com.",
			},
		],
	});
} finally {
	await vm.dispose();
}

Read more in the embedded API quickstart.