Browserbase Plugin for OpenCode

Use Browserbase cloud browsers with OpenCode instead of local Chrome.

What it does

This plugin intercepts browser automation commands and forwards them to Browserbase's cloud browser infrastructure. This gives you:

• Sandboxed, secure browser execution - Run browser automation in isolated cloud environments
• Session recording and debugging - Watch the AI browse in real-time via debug URLs
• Scalable browser automation - Cloud browsers with built-in proxy and stealth capabilities

Requirements

• OpenCode CLI
• Browserbase account with API key
• Node.js 18+ or Bun

Installation

Manual Installation

1. Clone this repository:

   git clone https://github.com/browserbase/opencode-browserbase.git

2. Copy to your OpenCode plugins directory:

   # Project-specific
   cp -r opencode-browserbase/.opencode/plugin your-project/.opencode/plugin
   
   # Or globally
   cp -r opencode-browserbase ~/.config/opencode/plugin/browserbase

3. Copy the core files to the plugin directory:

   cp opencode-browserbase/*.js your-project/.opencode/plugin/
   cp opencode-browserbase/package.json your-project/.opencode/plugin/

4. Install dependencies:

   cd your-project/.opencode/plugin
   npm install

Setup

Run the setup script to configure your Browserbase credentials:

./scripts/setup.sh

You'll be prompted for:

• Browserbase API Key - Get this from browserbase.com/settings
• Project ID - Find this in your Browserbase dashboard

Credentials are stored in ~/.browserbase/credentials.

Alternative: Environment Variables

You can also set credentials via environment variables:

export BROWSERBASE_API_KEY="your-api-key"
export BROWSERBASE_PROJECT_ID="your-project-id"

Usage

Once installed and configured, just use OpenCode normally. The plugin automatically:

1. On session start: Launches a cloud browser and starts the forwarding server
2. On browser commands: Forwards browser automation to Browserbase
3. On navigation: Shows you the live debug URL to watch the browser
4. On session end: Cleans up the browser session

Example

$ opencode

> Navigate to github.com and take a screenshot

[Browserbase] Server started (PID: 12345)
[Browserbase] Watch live at: https://www.browserbase.com/sessions/abc123/debug

I'll navigate to GitHub and capture a screenshot...

How it works

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│    OpenCode     │────▶│ Forwarding Server│────▶│   Browserbase   │
│                 │     │  (Unix Socket)   │     │  Cloud Browser  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                                         │
                        ┌──────────────────┐             │
                        │   CDP Protocol   │◀────────────┘
                        │   (WebSocket)    │
                        └──────────────────┘

1. OpenCode sends browser commands via the MCP browser bridge socket
2. The forwarding server intercepts these commands
3. Commands are translated to CDP (Chrome DevTools Protocol) and sent to Browserbase
4. Browserbase executes commands on a cloud browser
5. Results are returned through the same path

Plugin Structure

browserbase/
├── .opencode/
│   └── plugin/
│       └── browserbase.js       # OpenCode plugin (event hooks)
├── scripts/
│   ├── setup.sh                 # Credential setup
│   ├── session-start.sh         # Legacy hook (for reference)
│   ├── session-stop.sh          # Legacy hook (for reference)
│   └── browser-tool-log.sh      # Legacy hook (for reference)
├── index.js                     # Entry point
├── forwarding-server.js         # Socket interception & forwarding
├── browserbase-client.js        # Browserbase API & CDP client
└── package.json

Troubleshooting

"Failed to load credentials"

Run the setup script again:

./scripts/setup.sh

Server won't start

Check the server logs:

cat ~/.browserbase/state/server.log

Debug plugin issues

Check the debug log:

cat ~/.browserbase/state/hook-debug.log

Development

To test the plugin during development, you can load it from your project directory:

# The plugin will be loaded automatically from .opencode/plugin/
opencode

License

MIT

Links

• Browserbase
• OpenCode
• OpenCode Plugin Documentation