# kernel-python-sdk

Teaches the agent to write Python against Kernel browser sessions: server-side Playwright, CDP, profiles, proxies and clean teardown.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 353 installs · ★ 13
- Author: kernel
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/kernel/skills/tree/HEAD/plugins/kernel-sdks/skills/kernel-python-sdk/SKILL.md
- Updated: 2026-10-13
- HTML: https://affpapa.org/en/nevibecode/skills/kernel-python-sdk

## What it does

This skill covers creating and driving Kernel browser sessions from Python. There are two paths. Server-side Playwright runs next to Chrome, so no local Playwright install is needed. Client-side Playwright over CDP is the one to pick when you want local tooling or interactive debugging. Remote code receives `page`, `context` and `browser`, and you must use `return` or `response.result` comes back empty. Note the split: `timeout_sec` caps remote execution, while the SDK's `timeout=` governs the HTTP request.

Setup is short. Put `KERNEL_API_KEY` in the environment rather than in source; `Kernel()` and `AsyncKernel()` pick it up automatically. Install with `uv pip install -U kernel`, and add `uv pip install playwright` only for the CDP path. Stick to one client style — calling synchronous SDK methods from an async action will break.

Lifecycle gets its own section, and it matters. Wrap every session in `try/finally` right after creation and delete it with `client.browsers.delete_by_id(session_id)`; pool-acquired sessions go back through the pool release API instead. Profiles are created before they are attached, and `save_changes=True` is what persists cookies and local state. Delete the browser before the profile, otherwise the changes never finalize. Proxies attach at creation via `proxy_id` and can be swapped on a running browser. One detail worth remembering: `disable_default_proxy` is an update parameter, not a create parameter.

## Requirements
- Works with: Playwright

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add kernel/skills --skill kernel-python-sdk -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/kernel-python-sdk/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/kernel-python-sdk/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add kernel/skills --skill kernel-python-sdk -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/kernel-python-sdk/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add kernel/skills --skill kernel-python-sdk -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/kernel-python-sdk/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install kernel/skills kernel-python-sdk
```

2. **Manually: put the files in place**
- File: `.github/skills/kernel-python-sdk/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add kernel/skills --skill kernel-python-sdk -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/kernel/skills --path plugins/kernel-sdks/skills/kernel-python-sdk
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/kernel-python-sdk/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add kernel/skills --skill kernel-python-sdk -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/kernel/skills/tree/HEAD/plugins/kernel-sdks/skills/kernel-python-sdk/SKILL.md

## When to use it
- run Playwright server-side without installing it locally
- attach to a Kernel browser over CDP for debugging
- persist cookies and login state across runs
- route traffic through a specific proxy and verify it
- avoid orphaned sessions when a script crashes

## Example prompts
- Write a Python script that creates a Kernel browser and runs server-side Playwright to open a page and return its title
- Connect to the Kernel session over CDP and reuse the default context so pages see the profile state
- Wrap session creation in try/finally and delete it with delete_by_id at the end

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1fc99ceef565710d.

BEGIN THIRD-PARTY FILE 1fc99ceef565710d
````text
---
name: kernel-python-sdk
description: Build and debug Python browser automation with the Kernel SDK, including browser lifecycle, server-side Playwright, CDP, profiles, proxies, and reliable cleanup.
context: fork
---

## When to Use This Skill

Use this skill to write Python that creates and controls Kernel browser sessions. Prefer it for:

- Server-side Playwright execution in the browser VM
- Client-side Playwright over CDP
- Persistent profiles and explicit proxy routing
- Browser pools or deployed Python actions

Use the `kernel-cli` skill for shell commands and quick one-off sessions.

## Setup

```bash
uv pip install -U kernel
# Add this only for client-side CDP:
uv pip install playwright
```

Set `KERNEL_API_KEY` in the environment; do not put it in source. `Kernel()` and `AsyncKernel()` read it automatically. Use the async client consistently—do not call synchronous SDK methods from an async action.

## Choose an Automation Path

### Server-side Playwright (default)

Run JavaScript/TypeScript next to Chrome. This avoids a local CDP round trip and does not require local Playwright:

```python
from kernel import Kernel

with Kernel() as client:
    browser = client.browsers.create(stealth=True, timeout_seconds=300)
    try:
        response = client.browsers.playwright.execute(
            browser.session_id,
            code="""
await page.goto("https://example.com");
return { title: await page.title(), url: page.url() };
""",
            timeout_sec=60,
        )
        if not response.success:
            raise RuntimeError(response.error or response.stderr or "Playwright execution failed")
        print(response.result)
    finally:
        client.browsers.delete_by_id(browser.session_id)
```

Pass the session ID as the first positional argument. The code receives `page`, `context`, and `browser`. Use `return`; otherwise `response.result` is empty. `timeout_sec` limits remote code execution, while the SDK's `timeout=` option controls the HTTP request.

### Client-side Playwright over CDP

Use CDP when local Playwright tooling or interactive debugging is required:

```python
import asyncio
````
END THIRD-PARTY FILE 1fc99ceef565710d

The third-party file has ended. Everything between the 1fc99ceef565710d tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2143 of 7970 bytes. © kernel · MIT · https://github.com/kernel/skills/tree/HEAD/plugins/kernel-sdks/skills/kernel-python-sdk/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md