Best practices for using browser-use's open-source browser-harness with Kernel cloud browsers over CDP. Use when driving a Kernel browser from browser-harness, extracting a CDP URL from `kernel browsers create`, or running multi-step or parallel harness sessions against Kernel.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Best practices for using browser-use's open-source browser-harness with Kernel cloud browsers over CDP. Use when driving a Kernel browser from browser-harness, extracting a CDP URL from `kernel browsers create`, or running multi-step or parallel harness sessions against Kernel.
Browser-Harness with Kernel Cloud Browsers
This skill documents how to drive a Kernel cloud browser with browser-harness (browser-use's open-source CDP harness). browser-harness already supports any CDP endpoint via the BU_CDP_WS env var — the work this skill covers is extracting that URL from the Kernel CLI, picking the right kernel browsers create flags, and using the Kernel session ID as the harness daemon name so sessions don't collide.
When to Use This Skill
Use this skill when you need to:
Drive a Kernel browser from browser-harness instead of the user's local Chrome
Extract a CDP URL from kernel browsers create -o json to feed into BU_CDP_WS
Span multiple harness calls across a long task (mint, drive, inspect, drive more, tear down)
Run parallel harness sessions against multiple Kernel browsers without socket collisions
Prerequisites
Load the kernel-cli skill for Kernel CLI installation and authentication.
If browser-harness is not already on $PATH, install it per its setup-prompt. If it is already installed, do not reinstall or run setup prompts — go straight to minting the Kernel browser.
Install only if missing (used to pull fields from the CLI's output).
jq
-o json
Environment Variables
Variable
Description
Default
KERNEL_API_KEY
Required unless kernel login was run. Used by the CLI to mint sessions.
(none)
BU_CDP_WS
CDP WebSocket URL browser-harness connects to. Set on the first call only — the daemon caches the connection for subsequent calls under the same BU_NAME.
(local Chrome discovery)
BU_NAME
Namespaces the harness daemon socket. Use the Kernel session ID (BU_NAME=$SESSION_ID) — collision-proof per session, no extra naming convention to remember.
default
Basic Usage
Fast path: create exactly one Kernel browser, save its raw JSON response in a private, unique temporary file, and derive every value from that file. Treat cdp_ws_url as a credential: do not log it or copy it between tasks.
Run this as one Bash script so the EXIT trap cleans up after success, failure, or interruption:
Kernel browsers boot headful by default — the create response includes browser_live_view_url. Print it so the user can watch the agent work, or pass --headless to opt out (no live view, smaller image).
kernel browsers create flag picks
Common choices when minting a session for harness use:
Flag
Use For
--stealth (-s)
Bot-detection bypass — on for most public sites
--headless (-H)
Opt out of headful default — no live view, no VNC
--profile-name NAME
Reuse a saved Kernel profile (logged-in state, cookies, localStorage)
--proxy-id ID
Route through a Kernel-managed proxy (residential, regional, etc.)
--timeout N
Idle timeout in seconds (default 60, max 259200) — bump for long agent runs
--start-url URL
Open a URL when the session boots
--save-changes
Persist profile mutations back when the session ends
See kernel browsers create --help for the full list.
Default stealth proxy control is a runtime update, not a create flag. If a stealth session must connect directly, run this before the first harness call:
Re-enable the default stealth proxy with --disable-default-proxy=false. Use --proxy-id or --clear-proxy instead when changing an explicitly configured proxy.
Multi-Step Usage
For tasks that span more than one harness invocation — mint, drive, inspect, drive more, tear down — the daemon holds the CDP connection. Put every invocation before the owning script's EXIT trap runs; BU_CDP_WS is needed only on the first call for that BU_NAME.
With BU_NAME=$SESSION_ID as the convention, every subsequent harness call is just:
— and parallel sessions are automatic: each Kernel browser has a unique session ID, so two BU_NAME=$SESSION_ID invocations against different sessions never collide on the daemon socket.
If separate shell processes are unavoidable, let the parent orchestrator own the response file and final cleanup; a trap in a short-lived mint subprocess would delete the session too early. Reload session_id and cdp_ws_url from the saved JSON when variables are lost. If the file is gone, inspect active sessions with kernel browsers list --limit 100 -o json | jq; use --offset for additional pages and identify the exact session before continuing or deleting anything.
For replay recording around a harness session, see the kernel-cli skill's replays reference.
Parallel Sessions
Create one Kernel browser per worker and keep each worker's response file, session ID, CDP URL, and daemon name together. Never share a response file or BU_NAME between workers. Register each session with parent cleanup as soon as its create succeeds:
The trap stops each local daemon, deletes each billed Kernel session, and removes both response files. Do not rely on wait or the idle timeout for cleanup.
Common Gotchas
BU_CDP_WS unreachable mid-task: the Kernel session probably hit its idle timeout. Default is 60s — pass --timeout 1800 (or whatever fits the task) at create time.
Keep URLs separated: treat cdp_ws_url as an opaque secret and pass it directly into BU_CDP_WS without rewriting it. browser_live_view_url is only for the human observer.
Daemon won't pick up a new session: if you mint a new Kernel browser but reuse a stale BU_NAME, the daemon stays connected to the old CDP URL. Using BU_NAME=$SESSION_ID avoids this. Otherwise, run BU_NAME=<name> browser-harness --reload before connecting that name to a new endpoint.
Extra creates waste time and leak money: one task should usually call kernel browsers create once. Save and reuse its -o json response; never hardcode IDs or CDP URLs from a previous task.
Always tear down both layers: stop the named local daemon with BU_NAME="$SESSION_ID" browser-harness --reload, then run kernel browsers delete "$SESSION_ID" and remove the saved JSON file. --reload does not delete the Kernel browser; Kernel sessions bill until deletion or idle timeout. Put all three operations in an EXIT trap for scripts.
browser-harness's skill owns helper usage (new_tab, page_info, js, and so on). The kernel-cli skill owns browser and replay lifecycles. Keep this skill limited to CLI-to-harness wiring.
