Set up Kernel with an AI agent

name: Kernel
description: Use when building browser automation agents, web scraping
  workflows, or testing applications. Reach for Kernel when you need to control
  a real Chromium browser in the cloud, handle authentication and bot detection,
  run Playwright code, or execute computer-use actions on websites.
metadata:
  mintlify-proj: kernel
  version: "1.0"

Kernel Skill

Product summary

Kernel is a cloud-based browser infrastructure platform that runs isolated Chromium instances for agents and automation. Agents use Kernel to navigate websites, fill forms, extract data, and complete transactions without managing local browsers or handling bot detection. Access Kernel via REST API, SDKs (TypeScript, Python, Go), CLI, or MCP server. Key entry points: create a browser with POST /browsers, drive it with Playwright execution or computer controls, and manage state with profiles and vaults. The primary documentation is at https://www.kernel.sh/docs.

When to use

Reach for Kernel when:

• An agent needs to automate a website or web application
• You're building a scraper, form-filler, or checkout automation
• The target site has bot detection, CAPTCHA challenges, or requires authentication
• You need to run Playwright code or computer-use actions in a real browser without local infrastructure
• You're deploying long-running agents that need observability (live view, replays, telemetry)
• You need to scale to many concurrent browser sessions
• You're handling sensitive credentials (payment cards, passwords) that shouldn't touch the agent

Do not use Kernel for: static HTML parsing (use a lightweight HTTP client), unit testing (use a test framework), or work that doesn't require a real browser.

Quick reference

Creating and driving browsers

Task	Command/Code
Create a browser	kernel browsers create or POST /browsers
Get live view URL	Returned in browser_live_view_url on create
Run Playwright code	kernel.browsers.playwright.execute(session_id, {code: "..."})
Take a screenshot	kernel.browsers.computer.capture_screenshot(session_id)
Click at coordinates	kernel.browsers.computer.click_mouse(session_id, {x, y})
Type text	kernel.browsers.computer.type_text(session_id, {text})
Delete a browser	kernel browsers delete <session_id> or DELETE /browsers/{id}

Configuration options at browser creation

Option	Values	Use when
stealth	true / false	Site has bot detection; enables CAPTCHA solver
headless	true / false	High-volume work; reduces memory but may trigger detection
memory	1GiB, 2GiB, 4GiB (headless) or 8GiB, 16GiB (headful)	Adjust for memory-heavy pages or tab-heavy workflows
proxy	{id, name, mode}	Route through ISP, residential, or mobile IPs
profile	{id, name, save_changes}	Load saved cookies/auth; set save_changes: true to persist
timeout_seconds	60 to 259200	How long before idle browser is deleted
start_url	URL string	Navigate on creation
region	us-east, eu-west, ap-southeast	Run closer to your code or target

CLI essentials

kernel login                          # Authenticate with OAuth
kernel browsers create                # Create a browser
kernel browsers list                  # List active browsers
kernel browsers delete <id>           # Delete a browser
kernel profiles create --name <name>  # Create a profile
kernel proxies create --type residential  # Create a proxy
kernel deploy <file>                  # Deploy an app
kernel invoke <app> <action>          # Run an app action
kernel mcp install --target claude    # Install MCP for Claude

API key and authentication

• Set KERNEL_API_KEY environment variable for SDK/CLI/MCP authentication
• Create org-scoped keys for persistent backends; project-scoped keys for isolation
• Deployment-scoped keys are auto-injected when you deploy an app
• Use kernel login for OAuth in CLI; MCP server handles OAuth dynamically

Control surfaces (choose one per browser)

Surface	Best for	Trade-off
Playwright execution	Deterministic steps (navigate, fill, extract)	Needs valid selectors; each call is stateless
Computer controls	Vision-based agents, pixel-level interaction	Slower per step; requires screenshots
Browser REPL	Persistent state across turns; custom helpers	JavaScript only
CDP/WebDriver	Existing Playwright/Puppeteer code	Adds protocol fingerprint

Decision guidance

When to use stealth mode vs. direct egress

Condition	Use stealth	Use direct
Site has aggressive bot detection (Cloudflare, DataDome, PerimeterX)	✓
Site is public and doesn't check for bots		✓
You need CAPTCHA solving	✓
Low-latency is critical		✓

When to use profiles vs. managed auth vs. vault fill

Scenario	Use profiles	Use managed auth	Use vault fill
Save cookies and site data between sessions	✓
Kernel should handle login flow automatically		✓
Agent fills login form without seeing credentials			✓
Reauthenticate when session expires		✓
Preserve multi-site auth state	✓	✓

When to use browser pools vs. on-demand browsers

Situation	Use pools	Use on-demand
High-concurrency, burst traffic	✓
Need instant browser acquisition	✓
Custom viewport or GPU acceleration		✓
One-off or low-frequency work		✓
Want to absorb create-rate limits	✓

When to run your loop where

Loop type	Run in	Reason
Playwright execution (deterministic)	Anywhere; use API	Small payloads, low latency
Computer use (vision-based)	Code execution platform	Large image bandwidth per turn
Long-running agent	Code execution platform	Avoid network round trips
Scheduled scrape	Anywhere; use API	One call, one result

Workflow

Typical agent automation task

1. Understand the site — manually test it in a Kernel browser to see if it needs stealth, proxies, or authentication. Use kernel browsers create and open the live view URL.

2. Set up credentials — if the site requires login:

   • Create a vault and store credentials, or
   • Set up Managed Auth to handle login automatically, or
   • Use a profile with saved cookies from a previous authenticated session

3. Create the browser — call POST /browsers with your configuration:

   {
     "stealth": true,
     "proxy": {"name": "my-residential-proxy"},
     "profile": {"name": "authenticated-profile", "save_changes": true},
     "start_url": "https://example.com"
   }
   

4. Drive the browser — choose your control surface:

   • For deterministic steps: use Playwright execution with kernel.browsers.playwright.execute()
   • For vision-based steps: use computer controls with kernel.browsers.computer.capture_screenshot() and click_mouse()
   • Mix both: Playwright for DOM actions, computer controls when selectors fail

5. Extract and return data — use Playwright to read the DOM or computer controls to capture screenshots for the agent.

6. Save state — if save_changes: true on the profile, the browser's cookies and storage are saved when you delete it. Reuse the profile in the next browser.

7. Clean up — delete the browser with DELETE /browsers/{id} or let it timeout.

Deploying a long-running agent

1. Create an app with kernel create (scaffolds TypeScript or Python)
2. Define an action that takes a payload and returns a result
3. Deploy with kernel deploy <file> — Kernel mints a deployment-scoped API key
4. Invoke with kernel invoke <app> <action> --payload '{...}' or via API
5. Check logs with kernel deploy logs <deployment_id> --follow

Common gotchas

• Forgetting to delete browsers — browsers don't auto-delete when you close the CDP connection. Call DELETE /browsers/{id} or set timeout_seconds to avoid runaway costs.
• Profiles don't merge — only one browser can write to a profile at a time. Concurrent writes overwrite each other. Use separate profiles per writer or load read-only.
• Stealth mode adds latency — CAPTCHA solving and anti-detection checks take time. Test without stealth first, then add it only if needed.
• Selectors break on dynamic sites — if Playwright execution fails, fall back to computer controls (screenshot + click at coordinates).
• Headless browsers trigger detection — some sites notice headless mode. Use headful (default) unless memory is critical.
• Custom viewport restarts Chromium — setting a non-default viewport on creation takes several seconds. Use browser pools for instant acquisition.
• Managed Auth only works on supported flows — password + TOTP, SSO, and multi-step logins are supported. Passkey-only auth is not. Check the auth FAQ.
• Vault credentials don't auto-fill — use the fill API to inject credentials into a form; vaults don't automatically populate login fields.
• Rate limits on browser creation — your plan has a create rate separate from concurrency. Use browser pools to bypass it.
• CDP fingerprint leaks automation — if bot detection is aggressive, use computer controls instead of CDP/Playwright to avoid the protocol signature.

Verification checklist

Before submitting work with Kernel:

• Browser is deleted or will timeout (check timeout_seconds)
• Sensitive credentials are stored in a vault or managed auth, not logged
• Profile is saved if state needs to persist (save_changes: true)
• Stealth mode is enabled if the site has bot detection
• Proxy is configured if needed (residential, ISP, or mobile)
• Playwright execution and computer controls are used appropriately (DOM vs. screen)
• Screenshots and telemetry are captured if observability is needed
• Concurrency limits are respected (check org and project limits)
• API key is scoped correctly (org-wide, project-scoped, or deployment-scoped)
• Error handling covers rate limits, timeouts, and CAPTCHA solves

Resources

• Comprehensive page index: https://www.kernel.sh/docs/llms.txt — use this to find any page by topic
• Full documentation: https://www.kernel.sh/docs
• API Reference: https://www.kernel.sh/docs/api-reference/browsers/create-a-browser-session
• Quickstart: https://www.kernel.sh/docs/start/quickstart
• Bot detection guide: https://www.kernel.sh/docs/browsers/bot-detection/overview
• Profiles and state: https://www.kernel.sh/docs/browsers/profiles
• Authentication: https://www.kernel.sh/docs/auth/overview
• MCP server: https://www.kernel.sh/docs/reference/mcp-server
• CLI reference: https://www.kernel.sh/docs/reference/cli

---

For additional documentation and navigation, see: https://www.kernel.sh/docs/llms.txt