kernel-python-sdk

name	kernel-python-sdk
description	Build browser automation scripts using the Kernel Python SDK with Playwright and remote browser management.
context	fork

When to Use This Skill

Use the Kernel Python SDK when you need to:

• Build browser automation scripts - Create Python programs that control remote browsers
• Execute server-side automation - Run Playwright code directly in the browser VM without local dependencies
• Manage browser sessions programmatically - Create, configure, and control browsers from code
• Build scalable scraping/testing tools - Use browser pools and profiles for high-volume automation
• Deploy automation as actions - Package scripts as Kernel actions for invocation via API

When NOT to use:

• For CLI commands (e.g., kernel browsers create), use the kernel-cli skill instead
• For quick one-off tasks, the CLI may be simpler than writing code

Core Concepts

SDK Architecture

The SDK is organized into resource-based modules:

• kernel.browsers - Browser session management (create, list, delete)
• kernel.browsers.playwright - Server-side Playwright execution
• kernel.browsers.computer - OS-level controls (mouse, keyboard, screenshots)
• kernel.browser_pools - Pre-warmed browser pool management
• kernel.profiles - Persistent browser profiles (auth state)
• kernel.auth.connections - Managed auth (create, login, submit, follow, retrieve, delete)
• kernel.credential_providers - External credential providers (1Password)
• kernel.proxies - Proxy configuration
• kernel.extensions - Chrome extension management
• kernel.deployments - App deployment
• kernel.invocations - Action invocation

Two Automation Approaches

1. Server-side Execution (RECOMMENDED)

• Execute Playwright code directly in browser VM using kernel.browsers.playwright.execute(session_id, code="...")
• session_id must be passed as a positional argument (first parameter), not as id= keyword
• Response accessed via response.result - MUST use return in code to get data back
• Best for: Most use cases, production automation, parallel execution, actions

2. CDP Connection (Client-side)

• Connect Playwright to browser via CDP WebSocket URL
• Code runs locally, browser runs remotely; requires local Playwright installation
• Best for: Complex debugging, specific local development needs

Patterns Reference

Import Patterns

• Standard: from kernel import Kernel
• For actions: import kernel and from kernel import Kernel
• For typed payloads: from typing import TypedDict
• For CDP: from playwright.async_api import async_playwright

SDK Initialization

• client = Kernel() reads KERNEL_API_KEY from environment automatically

Action Handler Pattern

from typing import TypedDict
from kernel import Kernel

app = kernel.App("app-name")

class TaskInput(TypedDict):
    task: str

@app.action("action-name")
async def my_action(ctx: kernel.KernelContext, input_data: TaskInput):
    # Access input: input_data["task"] or input_data.get("task")
    ...

CDP Connection Pattern (Client-side)

async with async_playwright() as playwright:
    browser = await playwright.chromium.connect_over_cdp(kernel_browser.cdp_ws_url)
    context = browser.contexts[0] if browser.contexts else await browser.new_context()
    page = context.pages[0] if context.pages else await context.new_page()

Binary Data Handling

Binary data (screenshots, PDFs) returns as Node.js Buffer: {'data': [byte_array], 'type': 'Buffer'}

# Follow canonical pattern above, then:
if response.success and response.result:
    data = bytes(response.result['data'])
    with open("output.png", "wb") as f:
        f.write(data)

Installation

• uv pip install kernel or pip install kernel
• For CDP: uv pip install playwright

References

• Kernel Documentation: https://www.kernel.sh/docs
• API Reference: https://www.kernel.sh/docs/api-reference/
• Templates: https://www.kernel.sh/docs/reference/cli/create#available-templates
• Quickstart Guide: https://www.kernel.sh/docs/quickstart
• Examples: examples