Kernel Agent Browser

kernel/skills/plugins/kernel-cli/skills/kernel-agent-browser

by kernel657128912df878d874d480b82521698b327950b6No licenseListed Oct 9, 2026Updated Oct 9, 2026

Best practices for using agent-browser with Kernel cloud browsers. Use when automating websites with agent-browser -p kernel, tuning stealth or proxy behavior, persisting profiles, handling iframes, discovering Kernel session IDs or live views, or cleaning up cloud sessions.

Instructions onlySoftware DevelopmentAI & Agents
AI-generated overview

Best practices for automating websites with agent-browser through Kernel cloud browsers.

What it does
This skill documents how to drive agent-browser with the Kernel provider for cloud browser automation. It covers environment variables, stealth and proxy settings, profile persistence via a CDP workaround, semantic selectors, iframe handling, waiting strategies, login patterns, session discovery, live views, and cleanup. It also points to a reference guide for building site-specific automation skills.
When to use it
Use it when automating websites with agent-browser and Kernel cloud browsers, handling bot detection, persisting login sessions, working with iframes, or managing and cleaning up cloud browser sessions.
Requirements
Requires the agent-browser CLI with the Kernel provider, the Kernel CLI and authentication via a KERNEL_API_KEY, plus jq for session-matching commands. Network access is needed to reach Kernel cloud browsers. It ships no scripts; it is instructions only, with one reference document.

Agent-Browser with Kernel Cloud Browsers

This skill documents best practices for using agent-browser's built-in Kernel provider (-p kernel) for cloud browser automation.

When to Use This Skill

Use this skill when you need to:

  • Automate websites using agent-browser -p kernel commands
  • Handle bot detection on sites with aggressive anti-bot measures
  • Persist login sessions across automation runs using profiles
  • Work with iframes including cross-origin payment forms
  • Get live view URLs for debugging or manual intervention
  • Find the underlying Kernel session ID for advanced Playwright scripting
  • Create site-specific automation skills for new websites

References

  • Creating Site-Specific Skills [blocked] - Guide for building automation skills for specific websites

Prerequisites

Load the kernel-cli skill for Kernel CLI installation and authentication.

Environment Variables

Set these before your first agent-browser -p kernel call. The CLI holds state between invocations.

VariableDescriptionDefault
KERNEL_API_KEYRequired. Your Kernel API key for authentication(none)
KERNEL_HEADLESSRun browser in headless mode (true/false)true
KERNEL_STEALTHLaunch a stealth browser (true/false)false
KERNEL_TIMEOUT_SECONDSSession timeout in seconds300
KERNEL_PROFILE_NAMECurrently unusable with -p kernel in agent-browser 0.33.0; use the CDP workaround below(none)

Recommended Configuration

Set options explicitly; agent-browser reads them when it creates the provider session.

bash
export KERNEL_API_KEY="your-api-key"export KERNEL_TIMEOUT_SECONDS=600     # 10-minute timeout for complex workflowsexport KERNEL_HEADLESS=false          # Required when you need a live viewexport KERNEL_STEALTH=true            # Opt in for bot-sensitive sites# Do not set KERNEL_PROFILE_NAME with -p kernel; use the workaround below.

Profile Persistence

Warning: KERNEL_PROFILE_NAME doesn't work with -p kernel in agent-browser 0.33.0. It sends profile as a string instead of the object required by Kernel, so session creation fails with HTTP 400. It also doesn't set save_changes. Profiles must be pre-created.

Until this is fixed upstream, create the browser with the Kernel CLI and attach agent-browser over CDP. Don't combine -p kernel with --cdp.

bash
PROFILE_NAME=mysite  # Create once with: kernel profiles create --name mysitekernel profiles get "$PROFILE_NAME" >/dev/nullBROWSER=$(kernel browsers create --profile-name "$PROFILE_NAME" --save-changes --timeout 600 -o json)SESSION_ID=$(jq -er '.session_id' <<<"$BROWSER")CDP_URL=$(jq -er '.cdp_ws_url' <<<"$BROWSER")trap 'kernel browsers delete "$SESSION_ID" >/dev/null 2>&1 || true' EXIT
agent-browser --session mysite --cdp "$CDP_URL" open https://example.comagent-browser --session mysite snapshot -i# Run additional commands with --session mysite, then disconnect and end the Kernel session.agent-browser --session mysite closekernel browsers delete "$SESSION_ID"trap - EXIT

Don't print or share CDP_URL; it grants browser access. Deleting the CLI-created session finalizes --save-changes, so later sessions can reuse the authenticated profile.

Basic Usage

bash
agent-browser -p kernel open <url>        # Navigate to pageagent-browser -p kernel snapshot -i       # Get interactive elements with refsagent-browser -p kernel click @e1         # Click element by refagent-browser -p kernel fill @e2 "text"   # Fill input by refagent-browser -p kernel close             # Close the provider session

For provider-managed sessions, use -p kernel with each command. For the profile/CDP workaround, reuse the same --session name and don't add -p kernel.

Semantic Selectors (Recommended)

Instead of ephemeral @e refs that change on every page load, use semantic selectors via the find command for more stable, readable automation:

bash
# By ARIA role + accessible name (most stable)agent-browser -p kernel find role button click --name "Log In"agent-browser -p kernel find role textbox fill "[email protected]" --name "Email"
# By visible text contentagent-browser -p kernel find text "View Menus" clickagent-browser -p kernel find text "Submit Order" click
# By form label (great for inputs)agent-browser -p kernel find label "Username" fill "myuser"agent-browser -p kernel find label "Password" fill "secret123"
# By placeholder textagent-browser -p kernel find placeholder "Search..." type "query"
# By data-testid (if the site uses them)agent-browser -p kernel find testid "submit-btn" click
# By position (when needed)agent-browser -p kernel find first "li.item" clickagent-browser -p kernel find nth 2 ".card" hover

When to Use Which Selector

Selector TypeBest ForStability
find role --nameButtons, links, navigation⭐⭐⭐ Most stable
find labelForm inputs with labels⭐⭐⭐ Most stable
find textClickable text elements⭐⭐ Stable
find testidSites with test attributes⭐⭐⭐ Most stable
find placeholderSearch boxes, inputs⭐⭐ Stable
@e refsUnknown sites, quick iteration⭐ Ephemeral

Recommendation: Use find for production automation. Use @e refs for exploration and quick prototyping, then convert to semantic selectors.

Find the Kernel Session and Live View

Match agent-browser's CDP endpoint to the active Kernel session. Compare the URL without its query string: the CLI and agent-browser can hold different short-lived jwt query values for the same session. The endpoint's scheme, host, and path remain stable. This is more reliable than guessing from creation time when several sessions share a profile. This workflow requires jq.

bash
CDP_URL="$(agent-browser -p kernel get cdp-url)"CDP_ENDPOINT="${CDP_URL%%\?*}"SESSION_ID="$(  kernel browsers list --status active --limit 100 -o json |    jq -r --arg endpoint "$CDP_ENDPOINT" \      '.[] | select((.cdp_ws_url | split("?")[0]) == $endpoint) | .session_id' |    head -n 1)"test -n "$SESSION_ID"
kernel browsers view "$SESSION_ID"

Do not print or share the CDP URL; it grants browser access. Share a live view URL only with the intended user. A headless session has no live view. If you use --session <name>, include it on every agent-browser command, including get cdp-url.

Handling Bot Detection

Stealth and Proxy Routing

Stealth is opt-in in current agent-browser releases. Set KERNEL_STEALTH=true before the first command for a session; changing it later does not reconfigure the running browser.

A stealth browser can use Kernel's default stealth proxy. If that proxy causes a site-specific network or reputation failure and direct metro egress is acceptable, change the running session without disabling stealth:

bash
kernel browsers update "$SESSION_ID" --disable-default-proxy# Retry the navigation and compare behavior.
# Re-enable the default stealth proxy while continuing the same session.kernel browsers update "$SESSION_ID" --disable-default-proxy=false

Direct egress changes the public IP and can reduce anti-bot protection. Prefer the default proxy unless testing shows it is the problem. For a configured Kernel proxy, use --proxy-id <proxy-id>; remove it with --clear-proxy.

Manual Login Fallback

If automated login fails:

  1. Resolve SESSION_ID using the CDP-matching workflow above.
  2. Run kernel browsers view "$SESSION_ID" and give the URL only to the intended user.
  3. Ask the user to complete login, then continue in the same agent-browser session.
  4. To persist the login, use the CLI-created profile/CDP workflow above. Close agent-browser, then delete the Kernel session so --save-changes finalizes.

JavaScript Fallback for Tricky Elements

Some elements (especially on bot-protected sites) don't respond to standard commands:

bash
# Click by CSS selectoragent-browser -p kernel eval "document.querySelector('.submit-btn').click()"
# Fill by selector (with event dispatch)agent-browser -p kernel eval "  const el = document.querySelector('#email');  el.value = '[email protected]';  el.dispatchEvent(new Event('input', {bubbles: true}));  el.dispatchEvent(new Event('change', {bubbles: true}));"
# Click by test IDagent-browser -p kernel eval "document.querySelector('[data-testid=\"submit\"]').click()"

Anti-Bot Form Fields

Some payment processors (e.g., Point and Pay) use decoy form fields. Only fill fields matching specific patterns:

bash
agent-browser -p kernel eval "  const realInputs = Array.from(document.querySelectorAll('input'))    .filter(el => el.name && el.name.startsWith('xeiinput'));  // Fill only these inputs"

Handling Iframes

Same-Origin Iframes

Use the frame command to switch context:

bash
agent-browser -p kernel frame "#iframe-id"   # Switch to iframeagent-browser -p kernel snapshot -i          # Snapshot within iframeagent-browser -p kernel click @e1            # Interact within iframeagent-browser -p kernel frame main           # Return to main frame

Cross-Origin Iframes

Try agent-browser frame first; current releases can switch into iframe context, including many cross-origin frames. If an out-of-process or payment iframe still fails, resolve SESSION_ID and use Kernel's Playwright executor:

bash
kernel browsers playwright execute "$SESSION_ID" '  const frame = page.frameLocator("#payment-iframe");  await frame.locator("#card-number").fill("4111111111111111");  await frame.locator("#submit").click();'

Return to the main document with agent-browser -p kernel frame main after frame interactions.

Waiting Strategies

Smart waits are critical for fast, reliable automation. Using condition-based waits instead of fixed timeouts can reduce execution time by 50%+ while improving reliability.

Smart Waits (Recommended)

bash
# Wait for page load statesagent-browser -p kernel wait --load domcontentloaded  # DOM readyagent-browser -p kernel wait --load networkidle       # Network settled
# Wait for specific URL pattern (great for redirects after login)agent-browser -p kernel wait --url "**/dashboard"agent-browser -p kernel wait --url "**/order-confirmation"
# Wait for text to appear (great for dynamic content)agent-browser -p kernel wait --text "Password"        # Field appearedagent-browser -p kernel wait --text "Order confirmed" # Success message
# Wait for JavaScript conditionagent-browser -p kernel wait --fn "window.appReady === true"agent-browser -p kernel wait --fn "document.querySelector('.spinner') === null"
# Wait for element by CSS selectoragent-browser -p kernel wait "#login-form"agent-browser -p kernel wait ".results-loaded"

Fixed Waits (Last Resort)

bash
# Only when no condition is availableagent-browser -p kernel wait 2000

Element Refs Best Practices

Element refs (@e1, @e2, etc.) are ephemeral and change:

  • After page navigation
  • After significant DOM updates
  • Between browser sessions

Always take a fresh snapshot before interacting:

bash
agent-browser -p kernel snapshot -i# Now use the refs from this snapshotagent-browser -p kernel click @e5

Filtering Snapshots

bash
# Filter for specific elementsagent-browser -p kernel snapshot -i | grep -i "button\|submit"
# Scope to a specific areaagent-browser -p kernel snapshot -s "#main-content" -i

Login Patterns

Single-Page Form (Optimized)

Username and password on the same page:

bash
agent-browser -p kernel open https://example.com/loginagent-browser -p kernel wait --load domcontentloaded
# Use semantic selectors for stabilityagent-browser -p kernel find label "Email" fill "[email protected]"agent-browser -p kernel find label "Password" fill "secret123"agent-browser -p kernel find role button click --name "Sign In"
# Wait for actual redirect, not arbitrary timeoutagent-browser -p kernel wait --url "**/dashboard"

Two-Step Form (Optimized)

Username first, then password on a second screen:

bash
agent-browser -p kernel open https://example.com/loginagent-browser -p kernel wait --load domcontentloaded
# Step 1: Usernameagent-browser -p kernel find label "Username" fill "myuser"agent-browser -p kernel press Enter
# Wait for password field to appear (not a fixed sleep!)agent-browser -p kernel wait --text "Password"
# Step 2: Passwordagent-browser -p kernel find label "Password" fill "secret123"agent-browser -p kernel press Enter
# Wait for successful redirectagent-browser -p kernel wait --url "**/home"

Modal Login

Login form appears in a modal overlay:

bash
# Click login link to open modalagent-browser -p kernel find text "Log In" clickagent-browser -p kernel wait --text "Password"  # Wait for modal
# Fill modal fieldsagent-browser -p kernel find label "Email" fill "[email protected]"agent-browser -p kernel find label "Password" fill "password123"agent-browser -p kernel find role button click --name "Sign In"agent-browser -p kernel wait --url "**/dashboard"

Fallback: JavaScript for Tricky Modals

Some modals don't expose accessible labels:

bash
agent-browser -p kernel eval "document.querySelector('.login-link').click()"agent-browser -p kernel wait 1000
agent-browser -p kernel eval "  document.getElementById('username').value = '[email protected]';  document.getElementById('username').dispatchEvent(new Event('input', {bubbles: true}));  document.getElementById('password').value = 'password123';  document.getElementById('password').dispatchEvent(new Event('input', {bubbles: true}));  document.querySelector('button[type=submit]').click();"agent-browser -p kernel wait --url "**/dashboard"

Handling New Tabs

Some links open in new tabs:

bash
# Click link that opens new tabagent-browser -p kernel click @e38agent-browser -p kernel tab 1           # Switch to new tab (0-indexed)agent-browser -p kernel wait 2000agent-browser -p kernel snapshot -i     # Interact with new tab

Screenshots and Debugging

bash
# Take screenshotagent-browser -p kernel screenshot ~/Downloads/page.png
# Full page screenshotagent-browser -p kernel screenshot ~/Downloads/full.png --full
# View console messagesagent-browser -p kernel console
# View page errorsagent-browser -p kernel errors
# Get current URLagent-browser -p kernel get url

Session Management

Cleanup

Close the same named agent-browser session you opened. This saves profile changes and deletes its Kernel browser:

bash
agent-browser -p kernel close# Named session: agent-browser -p kernel --session site1 close

If agent-browser is unavailable or close fails, delete the orphan explicitly:

bash
kernel browsers delete "$SESSION_ID"

Do not use close --all when unrelated agent-browser sessions may be running.

Multiple Sessions

Run parallel browser sessions with named sessions:

bash
agent-browser -p kernel --session site1 open https://site1.comagent-browser -p kernel --session site2 open https://site2.comagent-browser -p kernel session list

Common Gotchas

  1. Refs change after navigation: Re-snapshot after links, submissions, or major DOM updates.
  2. Wait for outcomes: Use URL, text, load-state, or JavaScript conditions after asynchronous actions.
  3. Provider settings are launch-time settings: Close the current session before changing KERNEL_HEADLESS, KERNEL_STEALTH, or timeout.
  4. Profile persistence needs the CDP workaround: KERNEL_PROFILE_NAME is currently broken. Close agent-browser, then delete the CLI-created Kernel session to finalize --save-changes.
  5. Stealth is not sufficient for every site: Compare proxy routing, use manual login, or fall back to direct Playwright for difficult frames.

Quick Reference

bash
# Start a standard provider session (for persistence, use the CDP workflow above)export KERNEL_TIMEOUT_SECONDS=600agent-browser -p kernel open https://example.com
# Basic interaction with semantic selectors (recommended)agent-browser -p kernel wait --load domcontentloadedagent-browser -p kernel find label "Email" fill "[email protected]"agent-browser -p kernel find label "Password" fill "secret"agent-browser -p kernel find role button click --name "Submit"agent-browser -p kernel wait --url "**/success"
# Alternative: snapshot + refs (for exploration)agent-browser -p kernel snapshot -iagent-browser -p kernel fill @eN "text"agent-browser -p kernel click @eM
# Resolve the underlying session before manual interventionCDP_URL="$(agent-browser -p kernel get cdp-url)"CDP_ENDPOINT="${CDP_URL%%\?*}"SESSION_ID="$(kernel browsers list --status active --limit 100 -o json |  jq -r --arg endpoint "$CDP_ENDPOINT" \    '.[] | select((.cdp_ws_url | split("?")[0]) == $endpoint) | .session_id' |  head -n 1)"test -n "$SESSION_ID"kernel browsers view "$SESSION_ID"
# Cleanup (delete by ID only if close fails)agent-browser -p kernel close

Selector Cheat Sheet

bash
# Buttons and linksagent-browser -p kernel find role button click --name "Submit"agent-browser -p kernel find role link click --name "Next"agent-browser -p kernel find text "Click here" click
# Form inputsagent-browser -p kernel find label "Email" fill "[email protected]"agent-browser -p kernel find placeholder "Search" type "query"agent-browser -p kernel find testid "username-input" fill "myuser"
# Smart waitsagent-browser -p kernel wait --load domcontentloadedagent-browser -p kernel wait --text "Success"agent-browser -p kernel wait --url "**/dashboard"agent-browser -p kernel wait --fn "window.loaded === true"

Source and attribution

Source:kernel/skillsinplugins/kernel-cli/skills/kernel-agent-browserat commit6571289

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More in Software Development

Playground

anthropics

Featured

Builds self-contained interactive HTML playgrounds with controls, live preview, and copyable prompt output.

Software Development37Kupdated today

M5 Onboard

anthropics

Featured

Provisions M5Stack ESP32 boards by detecting them on USB, flashing UIFlow 2.0 firmware, and installing a MicroPython app bundle.

Software Development37Kupdated today

Cardputer Buddy

anthropics

Featured

Guides iterating on a Cardputer-Adv MicroPython app bundle: adding apps, pushing files over USB-serial, tailing logs, and running REPL commands.

Software Development37Kupdated today

Web Design Guidelines

vercel-labs

Featured

Reviews UI code against Web Interface Guidelines fetched from a remote source and reports findings as file:line entries.

Software Development32Kupdated 5 weeks ago

Vercel React Native Skills

vercel-labs

Featured

React Native and Expo best-practice rules covering list performance, animation, navigation, UI patterns, state, and monorepo setup.

Software Development32Kupdated 5 weeks ago

Vercel React Best Practices

vercel-labs

Featured

Vercel's React and Next.js performance guidelines, organized as 70 rules for writing, reviewing, and refactoring code.

Software Development32Kupdated 5 weeks ago