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

```bash
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:
   ```json
   {
     "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