From f3fe26523e2bcc9e686a7f6189e2e536bef47749 Mon Sep 17 00:00:00 2001 From: masnwilliams <43387599+masnwilliams@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:11:17 +0000 Subject: [PATCH 1/2] Add debug-browser-session skill to kernel-cli plugin Port the kernel-mcp-server debug-browser-session prompt into a skill so it's available via the skills marketplace without installing the MCP. Co-Authored-By: Claude Opus 4.7 --- README.md | 1 + .../skills/debug-browser-session/SKILL.md | 130 ++++++++++++++++++ 2 files changed, 131 insertions(+) create mode 100644 plugins/kernel-cli/skills/debug-browser-session/SKILL.md diff --git a/README.md b/README.md index 31232f1..5e5cfd0 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,7 @@ Command-line interface skills for using Kernel CLI commands. | **kernel-agent-browser** | Best practices for `agent-browser -p kernel` automation, bot detection handling, iframes, login persistence | | **kernel-auth** | Setup and manage Kernel authentication connections for any website with safety checks and reauthentication support | | **profile-website-bot-detection** | Profile a website for bot detection vendors using stealth vs non-stealth Kernel browsers; compare effectiveness and identify vendor products | +| **debug-browser-session** | Systematically debug a Kernel browser session — VM issues, network errors, Chrome crashes, page-load failures, and live-view problems — using the Kernel CLI | ### kernel-sdks diff --git a/plugins/kernel-cli/skills/debug-browser-session/SKILL.md b/plugins/kernel-cli/skills/debug-browser-session/SKILL.md new file mode 100644 index 0000000..bd886fb --- /dev/null +++ b/plugins/kernel-cli/skills/debug-browser-session/SKILL.md @@ -0,0 +1,130 @@ +--- +name: debug-browser-session +description: Systematically debug a Kernel cloud browser session — VM issues, network errors, Chrome crashes, page-load failures, and live-view problems. Use when a browser session misbehaves (e.g. ERR_HTTP2_PROTOCOL_ERROR, "browser not responding", blank/error pages, captcha or "checking your browser" blocks, live view not loading) and you have the session ID. Drives the Kernel CLI to inspect session status, screenshots, page state, VM logs, and network connectivity. +--- + +# Debug a Kernel Browser Session + +Diagnose a misbehaving Kernel cloud browser session using the Kernel CLI. The CLI has full access to the session's VM — status, screenshots, Playwright execution, log files, and in-VM command execution — which is everything you need to localize a failure to bot detection, a Chrome crash, a network/DNS problem, or live-view/WebRTC issues. + +## Inputs + +Two things drive the investigation: + +1. **Session ID** — the browser session to debug (e.g. `abc123example456xyz`). +2. **Issue description** — what's going wrong (e.g. "ERR_HTTP2_PROTOCOL_ERROR navigating to a specific site", "browser not responding", "page not loading", "live view is blank"). + +If either is missing, ask for it before proceeding. The issue description determines which checks below to weight. + +## Prerequisites + +Install and authenticate the Kernel CLI: + +```bash +brew install onkernel/tap/kernel # or: npm install -g @onkernel/cli +kernel auth status # confirm you're logged in (or KERNEL_API_KEY is set) +``` + +Explore commands recursively when you need options: + +```bash +kernel --help +kernel browsers --help +kernel browsers fs --help +kernel browsers process --help +kernel browsers playwright --help +``` + +## Core CLI commands + +Substitute your session ID for ``. + +### Session status +```bash +kernel browsers get +``` + +### Screenshot the current state +```bash +kernel browsers screenshot +``` + +### Inspect page state via Playwright +```bash +kernel browsers playwright execute "return { url: page.url(), title: await page.title() }" +``` + +### Read VM log files +```bash +kernel browsers fs read-file --path /var/log/supervisord.log +kernel browsers fs read-file --path /var/log/supervisord/chromium +kernel browsers fs read-file --path /var/log/supervisord/neko +``` + +### List files in the VM +```bash +kernel browsers fs ls --path /var/log +``` + +### Run commands inside the VM +```bash +kernel browsers process exec -- curl -I https://example.com +kernel browsers process exec -- cat /etc/resolv.conf +``` + +### Check cookies via Playwright +```bash +kernel browsers playwright execute "const cookies = await page.context().cookies(); return { count: cookies.length, domains: [...new Set(cookies.map(c => c.domain))] }" +``` + +## Common issues & solutions + +### Network errors (ERR_HTTP2_PROTOCOL_ERROR, ERR_CONNECTION_RESET, etc.) +Bot detection is a common cause. Many sites use CDNs like Cloudflare, Imperva, or Akamai that fingerprint browsers and block automation. + +Signs of bot detection: +- `curl` works from the VM but Chrome shows an error +- "Access Denied", captcha pages, or "Checking your browser…" messages +- `stealth: false` in the browser config (check with `kernel browsers get`) + +Solutions: enable `stealth: true`, use profiles with real auth, or try shorter session lifetimes. + +### Browser not responding +Cause: Chrome process crashed or hung. +Check: supervisor logs for chromium restart events. +Solutions: confirm the timeout wasn't reached, look for memory issues in the logs, create a new session. + +### Page not loading +Cause: network, DNS, or proxy issues. +Check: `curl` from inside the VM, `/etc/resolv.conf` for DNS config, proxy settings if one is configured. + +### Live view not working +Cause: Neko/WebRTC issues. +Check: Neko logs for connection errors. +Solutions: check for a firewall blocking WebRTC, verify the browser isn't in headless mode. + +## Expected log entries (normal operation) + +These are normal and don't indicate problems: +- `Failed to call method: org.freedesktop.DBus.Properties.GetAll` — DBus permission (expected in container) +- `vkCreateInstance: Found no drivers` — no GPU in the VM (expected) +- `DEPRECATED_ENDPOINT` for GCM — Google deprecation (harmless) +- `SharedImageManager::ProduceMemory` errors — GPU-related (not critical) + +## Debugging checklist + +- [ ] Session exists and is active +- [ ] Screenshot shows expected content (or reveals the error) +- [ ] Current URL is as expected +- [ ] Supervisor logs show all services running +- [ ] Network connectivity works (curl test) +- [ ] No critical errors in chromium logs +- [ ] Cookies/session state are correct + +## Suggested order + +1. Get browser info to confirm the session is active. +2. Take a screenshot to see the current state. +3. Check the page URL to see whether it's on an error page. +4. Test network connectivity if seeing connection errors. +5. Review logs for specific error patterns. From 998c7bfc3717e2d3a6ac167012be66b4ec93045b Mon Sep 17 00:00:00 2001 From: masnwilliams <43387599+masnwilliams@users.noreply.github.com> Date: Fri, 26 Jun 2026 17:10:52 +0000 Subject: [PATCH 2/2] Fix CLI commands and reduce duplication in debug-browser-session skill - Correct screenshot command to `browsers computer screenshot --to` - Correct file listing to `browsers fs list-files` - Note stealth is creation-time; recreate session rather than toggle - Add `browsers view` to live-view troubleshooting - Cross-reference kernel-cli skill instead of re-documenting install/auth Co-Authored-By: Claude Opus 4.7 --- .../skills/debug-browser-session/SKILL.md | 25 ++++--------------- 1 file changed, 5 insertions(+), 20 deletions(-) diff --git a/plugins/kernel-cli/skills/debug-browser-session/SKILL.md b/plugins/kernel-cli/skills/debug-browser-session/SKILL.md index bd886fb..ffda882 100644 --- a/plugins/kernel-cli/skills/debug-browser-session/SKILL.md +++ b/plugins/kernel-cli/skills/debug-browser-session/SKILL.md @@ -18,22 +18,7 @@ If either is missing, ask for it before proceeding. The issue description determ ## Prerequisites -Install and authenticate the Kernel CLI: - -```bash -brew install onkernel/tap/kernel # or: npm install -g @onkernel/cli -kernel auth status # confirm you're logged in (or KERNEL_API_KEY is set) -``` - -Explore commands recursively when you need options: - -```bash -kernel --help -kernel browsers --help -kernel browsers fs --help -kernel browsers process --help -kernel browsers playwright --help -``` +Load the `kernel-cli` skill for Kernel CLI installation and authentication. Its references cover the full command surface (`browser-management`, `filesystem-ops`, `process-execution`, `computer-controls`) when you need options beyond the ones below. ## Core CLI commands @@ -46,7 +31,7 @@ kernel browsers get ### Screenshot the current state ```bash -kernel browsers screenshot +kernel browsers computer screenshot --to screenshot.png ``` ### Inspect page state via Playwright @@ -63,7 +48,7 @@ kernel browsers fs read-file --path /var/log/supervisord/neko ### List files in the VM ```bash -kernel browsers fs ls --path /var/log +kernel browsers fs list-files --path /var/log ``` ### Run commands inside the VM @@ -87,7 +72,7 @@ Signs of bot detection: - "Access Denied", captcha pages, or "Checking your browser…" messages - `stealth: false` in the browser config (check with `kernel browsers get`) -Solutions: enable `stealth: true`, use profiles with real auth, or try shorter session lifetimes. +Solutions: stealth is set at creation and can't be toggled on a live session, so recreate it with `kernel browsers create --stealth`; use profiles with real auth; or try shorter session lifetimes. ### Browser not responding Cause: Chrome process crashed or hung. @@ -100,7 +85,7 @@ Check: `curl` from inside the VM, `/etc/resolv.conf` for DNS config, proxy setti ### Live view not working Cause: Neko/WebRTC issues. -Check: Neko logs for connection errors. +Check: fetch the live view URL with `kernel browsers view ` and open it; check Neko logs for connection errors. Solutions: check for a firewall blocking WebRTC, verify the browser isn't in headless mode. ## Expected log entries (normal operation)