bb-ide-plugin

Give bb a real browser. This plugin lets any bb agent open a Kernel cloud browser, watch it live, and drive it — right from a thread, on your hosted bb workspace, no local setup beyond an API key.

Quick start

The recommended way to install is straight from the community plugin list:

1. Go to Extensions in the sidebar
2. Find KERNEL Browser in the community plugin list and click install
3. In Configuration, click the its Settings page hyperlink
4. Enter the KERNEL_API_KEY you get from the Kernel dashboard: https://dashboard.onkernel.com/kernel/api-keys

Prefer to install a specific version, or the plugin isn't showing up in the list yet? Install it directly from its git URL instead — see the Quick start section:

https://github.com/kernel/bb-ide-plugin

1. Go to Extensions in the sidebar
2. Click on Installed Plugins
3. Click the down arrow next to New Plugin
4. Click Install from source
5. Enter https://github.com/kernel/bb-ide-plugin and click Install Plugin
6. In Configuration, click the its Settings page hyperlink
7. Enter the KERNEL_API_KEY you get from the Kernel dashboard: https://dashboard.onkernel.com/kernel/api-keys

Why you'd want this

Kernel gives any bb agent a real, cloud-hosted browser to work with. With this plugin, an agent can:

• Log into real accounts and get real work done — check a dashboard, file a form, pull a report — on sites that need a real, cookie-carrying browser, not just an HTTP fetch.
• Get past bot detection that blocks plain scrapers, with stealth handling built in (--stealth).
• Let you watch it happen. Every session ships a live view URL you can open in a tab and watch the agent click around in real time — no more wondering what it's actually doing out there.
• Keep running after you walk away. The browser lives in the cloud, not in your editor. Close your laptop, resume the thread tomorrow, and the session (or its result) is still there.
• Do all of this from a hosted bb workspace — the browser is already cloud-hosted, so there's nothing to run locally and nothing tying the session to any one machine.

What it adds

• bb kernel-browser open|list|snapshot|click|type|eval|close|replay-start|replay-stop|replay-list — see skills/kernel-browser/SKILL.md for the full command reference.
• Native agent tools (kernel_browser_open, _snapshot, _click, _type, _eval, _close, _replay_start, _replay_stop, _replay_list) that wrap the same commands, so a session with native tool support doesn't need to shell out to the CLI.
• Video replays: record a target's session (replay-start), stop it to persist the video (replay-stop), and list past recordings with their view URLs (replay-list) — same target ownership rules as everything else.
• Managed auth: bb kernel-browser auth-create|auth-list|auth-get|auth-login|auth-wait|auth-delete get a Kernel profile authenticated against a domain through Kernel's own hosted login page — this plugin never sees, types, or stores a password or code. See skills/kernel-managed-auth/SKILL.md.
• Three inline embeds, all rendered right in the message stream instead of a side panel: ::kernel-live{target-id="<target-id>"} for a target's live view, ::kernel-replay{target-id="<target-id>" replay-id="<replay-id>"} for a finished (or still-processing) recording, and ::kernel-auth-login{connection-id="<connection-id>"} for a hosted login page. kernel_browser_open, kernel_browser_replay_stop, and kernel_auth_login nudge the model to include these automatically.
• Target ownership tracking: every action is scoped to a target this plugin opened. Acting on an unknown or already-closed target fails with a clear error instead of silently doing nothing.
• Automatic cleanup: a thread's open targets are closed when the thread is archived or deleted, so Kernel sessions don't run (and bill) forever after a thread ends.

Install

On your hosted bb workspace, you just need a Kernel API key:

bb plugin install git:https://github.com/kernel/bb-ide-plugin.git@main
bb plugin config kernel-browser set apiKey <your-kernel-api-key>
bb plugin reload kernel-browser

Check status with bb plugin list — it reports needs-configuration until apiKey is set. Once configured, ask any agent in the workspace to open a browser and it's ready to go.

Development

npm install
npm run typecheck
npm test

npm test runs the unit suite against @get-bb/plugin-sdk/testing's fake plugin host — no running bb server or live Kernel API key required; the Kernel client is mocked. Against a real bb checkout, bb plugin dev (run from this directory) watches sources and reloads the plugin on every save.

bb plugin build (no server required — it downloads its own build toolchain on first use) compiles dist/server.js and dist/app.js and is what a git: install runs automatically.

Architecture

• src/kernel-client.ts — thin wrapper over @onkernel/sdk. Uses Kernel's Playwright Execution API (code runs server-side, in the same VM as the browser) for navigation/click/type/eval, and the Computer Use API for coordinate-based fallback actions. This avoids adding a CDP fingerprint on top of Kernel's own stealth handling.
• src/kernel-auth-client.ts — thin wrapper over @onkernel/sdk's auth.connections resource (create/get/list/login/delete). Unlike targets, connections aren't tracked in this plugin's own store: they're meant to be reused across threads (that's the point of a stable profile), and they're already scoped by the org's Kernel API key the same way targets are.
• src/store.ts — the plugin's own SQLite table of open targets (target_id, thread_id, created_by, live view URL, timestamps), used to enforce that every command only acts on a target this plugin opened.
• src/commands.ts — the actual open/list/snapshot/click/type/eval/close/replay and auth-create/list/get/login/wait/delete logic, shared by the CLI, the agent tools, and the RPC layer.
• src/cli.ts, src/server.ts — bb.cli.register / bb.agents.registerTool glue for the browser commands and plugin wiring (settings, event handlers).
• src/auth-tools.ts — the auth CLI command metadata and kernel_auth_* agent tool registrations, factored out of server.ts the same way rpc.ts already is.
• src/rpc.ts, app.tsx — the kernel-live, kernel-replay, and kernel-auth-login message directives' data plane (look up a target, replay, or auth connection by id; close a target) and UI (the embedded iframes).

License

MIT