---
title: Add the KERNEL browser
description: Drive a cloud browser that can sign in to the app your issues are about. Bugs that only reproduce behind a login become something Foreman can watch happen.
type: guide
summary: One registry command, one Connect connector, a shadowed connection carrying the approval gate, and the per-user consent limit that decides which runs can use it.
related:
  - /docs/tools
  - /docs/trust-model
  - /docs/stations
---

# Add the KERNEL browser



<CopyPrompt
  className="block"
  text={`Help me customize the eve Software Factory template. I want to add KERNEL so the agent can drive a cloud browser, including signing in to sites through KERNEL's managed auth.

Ground truth first: read AGENTS.md in the repository root, read agent/extensions/github.ts as the in-repo example of an extension mount, and read https://www.kernel.sh/docs/integrations/vercel/eve-extension plus node_modules/eve/docs/extensions.md before writing code. Do not hand-write the mount if the registry provides it.

1. Run: eve add extension/kernel
 This installs @onkernel/eve-extension and writes a mount under agent/extensions/. The extension needs eve 0.25 or later and Node 24; the template ships both, but confirm in package.json rather than assuming. Show me the generated file before changing it.
2. Configure the mount with Vercel Connect, not an API key: kernel({ connect: "kernel/kernel-mcp" }). Leave KERNEL_API_KEY unset everywhere, and tell me if you find it already set, because the extension falls back to it. If the generated file points at the older domain-based connector (mcp.onkernel.com/eve-extension), prefer the current registry form and say so.
3. Convert the mount into a directory so the browser connection can carry an approval gate: agent/extensions/kernel/extension.ts holds the mount, and agent/extensions/kernel/connections/browser.ts shadows the extension's built-in browser connection. Use defineMcpClientConnection from eve/connections with url https://mcp.onkernel.com/mcp, auth connect("kernel/kernel-mcp") from @vercel/connect/eve, approval once() from eve/tools/approval, and tools.allow set to exactly the seven tools the extension mounts by default: manage_browsers, execute_playwright_code, computer_action, manage_auth_connections, manage_profiles, manage_proxies, manage_replays. Use allow, not block, so tools the server adds later stay undiscovered too.
4. Do not add browser_curl, manage_credentials, exec_command, or manage_browser_pools to the allowlist. The extension ships them off to limit an autonomous agent's blast radius, and nothing in this factory needs them.
5. Tell me the setup commands I need to run myself, and do not run them:
 vercel link, vercel connect create kernel --name kernel-mcp --connection-method mcp, vercel connect attach kernel/kernel-mcp.
 Tell me the --connection-method flag needs Vercel CLI 58.8.0 or later.
6. Important: connect("kernel/kernel-mcp") is per-user consent, so each person authorizes in their own browser before their first tool call. Unattended factory runs (the factory label and the red-CI fix loop) have nobody to complete that flow. Confirm this in the eve connections docs, then tell me plainly which of Foreman's surfaces can and cannot use the browser.
7. Do not mount this extension under agent/subagents/. Stations run in task mode and cannot park for a consent prompt, an approval card, or a sign-in hand-off. If I ask for it later, explain the failure mode before doing it.
8. Explain the approval choice back to me instead of copying by reflex. once() parks the first browser action of a session for the person driving it, and agent/connections/linear.ts shows the predicate alternative. Say why a connection whose tools act inside logged-in sessions warrants a gate that this repo's read-oriented connections do not carry.

Finish by running pnpm validate and confirming 0 errors and 0 warnings, then run npx eve info and show me the kernel mount in the discovered surface with only the seven allowed tools. Do not deploy.

Full recipe, with the reasoning behind each step: https://ask-foreman.dev/recipes/add-the-kernel-browser`}
/>

KERNEL's eve extension packages one connection to its hosted Model Context Protocol (MCP) server and gives Foreman a cloud browser to drive end to end, with managed auth for pages that sit behind a sign-in.

## When to use it

Reach for this when the work needs a page exercised rather than read. Bug reports describe flows that only break after a sign-in, checkout paths that fail on the third step, dashboards that render wrong for one account type, and the repository alone cannot reproduce any of it. Foreman can then walk the same flow in a real browser, signed in the way the reporter was, and watch where it breaks.

The limit decides whether it is worth it for you. `connect("kernel/kernel-mcp")` is per-user consent, so the browser works from mentions, Linear sessions, and the dev TUI, and never from the unattended pipeline. If your factory runs mostly on labeled issues, this buys you less than it looks.

Tools appear to the model as `kernel__browser__<name>`, and a `browse` skill mounts beside them as the loop that drives a task end to end, surfacing the live-view URL so you can watch or take over.

The connection mounts seven browser tools:

| Tool                      | What Foreman uses it for                                          |
| ------------------------- | ----------------------------------------------------------------- |
| `manage_browsers`         | Start and stop browser sessions, each with a live-view URL        |
| `execute_playwright_code` | Drive the live page with Playwright                               |
| `computer_action`         | Click, type, scroll, and screenshot when code is the wrong tool   |
| `manage_auth_connections` | Sign in through KERNEL managed auth instead of typing credentials |
| `manage_profiles`         | Keep cookies and logins so the next browser starts signed in      |
| `manage_proxies`          | Route the browser through a chosen proxy type or geography        |
| `manage_replays`          | Record a session as an MP4, on paid KERNEL plans                  |

## What it touches

| File                                             | Change                                                                      |
| ------------------------------------------------ | --------------------------------------------------------------------------- |
| `agent/extensions/kernel/extension.ts`           | The mount, written by `eve add extension/kernel` and moved into a directory |
| `agent/extensions/kernel/connections/browser.ts` | Shadows the extension's built-in connection to add the approval gate        |
| Vercel Connect                                   | The `kernel-mcp` connector, created and attached with the Vercel CLI        |
| `package.json`                                   | `@onkernel/eve-extension`                                                   |

## Before you run it

Consent is per person, not per deployment. Every teammate who wants Foreman to drive a browser grants it once in their own browser, and Vercel Connect caches that grant across threads and sessions.

There is a running cost too. Vercel Connect bills per token request, browser sessions run against your KERNEL plan, and the mount widens the tool surface the model searches through on the turns that use it.

Everything the browser renders is text from the open web, read while the profile may be signed in to your accounts. Treat page content the way the [trust model](/docs/trust-model) treats issue bodies: as input, not instruction. The `once()` gate, and the browse skill handing sign-ins and sensitive actions back to you, are what keep a steered session from acting alone.

## What the mount looks like

The mount itself is one line, pointed at the Connect connector:

```ts title="agent/extensions/kernel/extension.ts"
import kernel from "@onkernel/eve-extension";

export default kernel({ connect: "kernel/kernel-mcp" });
```

Under a directory mount, a same-named consumer connection wins over the extension's own, which is how the approval gate gets in. The shadow restates what the built-in `browser` connection already does, then adds the one thing it lacks:

```ts title="agent/extensions/kernel/connections/browser.ts"
import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";
import { once } from "eve/tools/approval";

export default defineMcpClientConnection({
  url: "https://mcp.onkernel.com/mcp",
  description: "KERNEL: cloud browsers, managed auth, profiles, and replays.",
  auth: connect("kernel/kernel-mcp"),
  approval: once(),
  tools: {
    allow: [
      "manage_browsers",
      "execute_playwright_code",
      "computer_action",
      "manage_auth_connections",
      "manage_profiles",
      "manage_proxies",
      "manage_replays",
    ],
  },
});
```

KERNEL is a first-class connector, and the `--connection-method` flag needs Vercel CLI 58.8.0 or later:

```bash
vercel link
vercel connect create kernel --name kernel-mcp --connection-method mcp
vercel connect attach kernel/kernel-mcp
```

<Callout type="warn" title="This is per-user consent, so unattended runs cannot use it">
  `connect("kernel/kernel-mcp")` authorizes each end user in their own browser before their first tool call. Neither the factory-label run nor the red-CI fix run has anybody at a browser, so neither can complete that flow. The browser is usable from mentions, Linear sessions, and the dev TUI, but not from the unattended pipeline.
</Callout>

That constraint differs from the Linear connection already in the template, which uses app-scoped auth through `linearAuth` and therefore works without a person present.

## Signing in with managed auth

Foreman never types your password. `manage_auth_connections` attaches a domain to a browser profile: Foreman creates a connection for the site, KERNEL returns a hosted login page, and you complete the sign-in there yourself. Google, GitHub, and Microsoft SSO buttons work there, and KERNEL handles TOTP, SMS, and email one-time codes in the same flow.

Once the login succeeds, KERNEL saves the authenticated session to the profile named on the connection. Every later browser launched with that profile starts already signed in, to every domain the profile carries, so one interruption covers all the sessions that follow.

When the session eventually expires, someone signs in again through a fresh hosted link. KERNEL can skip that step by storing the credential and re-authenticating on its own, but that requires the `manage_credentials` tool this recipe keeps out. Either way, profile state is encrypted, and nothing typed on the hosted page is returned through the API or shown to the model.

## What stays out

KERNEL's MCP serves more than the seven tools above. The extension already ships four of them off, to limit what an autonomous agent can reach: `browser_curl`, `manage_credentials`, `exec_command`, and `manage_browser_pools`. The shadowed connection keeps them off by listing what it wants through `tools: { allow: [...] }`, so a tool the server adds later stays undiscovered too.

`manage_credentials` is the one to be deliberate about. It stores a secret so KERNEL can re-run a login without anyone present, and keeping it out means no sign-in happens unless a person is there to do it.

## Verify

```bash
pnpm validate
npx eve info
```

`npx eve info` should show the kernel mount's `browser` connection with only the seven allowed tools. If `exec_command` or `manage_credentials` shows up, the shadow connection is not being picked up.

Then run `pnpm dev` and ask Foreman to open a page. The first call triggers the Connect consent in your browser, the first browser action after that parks on the `once()` card, and the session reports a live-view URL you can watch it work through.

## What to expect

Browser time earns its place when the report describes a flow, especially one behind a sign-in. On a refactor or a repository-internal bug, Foreman leaves the browser alone and nothing runs against your KERNEL plan.

## FAQ

<Accordions type="single">
  <Accordion title="Can the unattended pipeline use the browser?">
    No. `connect("kernel/kernel-mcp")` authorizes each person in their own browser before their first tool call, and neither the factory-label run nor the red-CI fix run has a person present, so neither can complete that flow.

    The auth shape is not the only reason. An unattended run is driven by an issue body, and handing that input a browser that executes arbitrary Playwright inside logged-in sessions is exactly the configuration KERNEL's own security guidance warns against. If an unattended run needs something from behind a login, have an attended session record the durable finding in the [factory brain](/docs/memory), which every run reads.
  </Accordion>

  <Accordion title="Why not use KERNEL_API_KEY? It would work unattended.">
    The extension does accept a key, and `connect` takes precedence when both are set, so nothing breaks if one exists. It is still the wrong shape for this template.

    One key is one shared credential, so every caller acts as the whole KERNEL organization, sharing the same profiles, the same stored sessions, and the same spend. KERNEL positions the key for personal, single-tenant agents. This factory has many callers with different trust levels, which is what per-user consent is for.
  </Accordion>

  <Accordion title="Can a station use the browser?">
    No. Stations run in task mode, which cannot pause for a person, and this mount pauses in three places: the Connect consent on first use, the approval card from `once()`, and the hand-off when a page wants a sign-in. Mounting the extension under `agent/subagents/` therefore fails on the first browser call.

    The orchestrator drives the browser itself and weaves what it saw, including screenshots and the live-view URL, into the delegation message instead.
  </Accordion>

  <Accordion title="Why gate the browser when Sentry and Context.dev are not gated?">
    Those connections read. This one acts: `execute_playwright_code` runs whatever code the model writes, inside sessions that may be signed in to your accounts, and everything the browser renders is text that can try to steer the model.

    `once()` prices that risk at one approval card per session, answered by the person already driving it. KERNEL's own docs note the default mount has no approval gate and recommend adding one for team agents, and the shadowed connection is the documented place to put it.
  </Accordion>

  <Accordion title="What does adding the extension cost?">
    Three things. Vercel Connect bills per token request, browser sessions run against your KERNEL plan (and `manage_replays` needs a paid one), and every mount widens the tool surface the model has to search through with `connection_search`, which costs context on each turn that uses it.
  </Accordion>
</Accordions>


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)