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] 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.