> ## Documentation Index
> Fetch the complete documentation index at: https://libretto.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Kernel

> Run Libretto sessions on Kernel's managed browser infrastructure.

Kernel is a managed browser provider. Use it when you want Libretto's local CLI and workflow runtime, but you do not want to run Chromium on your own machine or cloud infrastructure.

## Configure Kernel

Create a Kernel API key, then add it to the repo root `.env` file. Libretto loads `.env` automatically before running CLI commands.

```dotenv theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
# inside .env
KERNEL_API_KEY=<kernel-api-key>
```

Optional Kernel settings can go in the same file:

```dotenv theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
# inside .env
KERNEL_HEADLESS=true
KERNEL_STEALTH=false
KERNEL_TIMEOUT_SECONDS=300
```

`KERNEL_ENDPOINT` is only needed if Kernel gives you a custom API endpoint.

Then set Kernel as the workspace's default browser provider in `.libretto/config.json`:

```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "version": 1,
  "provider": "kernel"
}
```

You can also use `--provider kernel` on a single command instead of changing the config file.

## Open a session

Open a page with the configured Kernel provider:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx libretto open https://example.com --session kernel-demo
```

If you did not set `provider` in `.libretto/config.json`, pass it for this command instead:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx libretto open https://example.com --provider kernel --session kernel-demo
```

After the session is open, use the normal Libretto commands:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx libretto snapshot --session kernel-demo
npx libretto exec --session kernel-demo "await page.title()"
npx libretto close --session kernel-demo
```

## Run a workflow

Run workflows normally when `provider` is set in `.libretto/config.json`:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx libretto run ./workflow.ts --headless
```

Or pass the provider for a single run:

```bash theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx libretto run ./workflow.ts --provider kernel --headless
```

The workflow code does not need to change. Libretto creates the Kernel browser session, connects to it over CDP, runs the workflow, and closes the provider session when the run finishes.

## When to use Kernel

Choose Kernel when you want a managed browser runtime with minimal infrastructure work. If you need to own the container runtime, scheduler, network, and secrets layer yourself, use [GCP](/alternative-providers/gcp) or [AWS](/alternative-providers/aws) instead.