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

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Run Playwright and browser sessions with Kernel

> Give Guild agents control over Kernel cloud browsers: create sessions, run Playwright code, perform computer actions, and manage profiles and pools.

Integrations · Kernel

A Guild agent controls Kernel cloud browsers to automate web tasks without exposing credentials to agent code. Guild injects your Kernel API key server-side through its credential proxy. Credential policies let you restrict which browser operations each agent or workspace can call.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Kernel.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Kernel to your first agent.

## What the Kernel integration exposes

The tools cover browser session lifecycle: create, update, and delete sessions, and acquire or release browsers from pools. Agents can execute Playwright code or run JavaScript in a persistent Node.js runtime, perform low-level computer actions such as clicking, typing, scrolling, and dragging, and manage reusable profiles that persist state across sessions. Recording and replay tools let agents start and stop session recordings and list saved replays.

## How it works

**1. Open Credentials in Guild**

Go to Access & setup > Credentials in your Guild account or organization. This page lists connected credentials and shows a gallery of available integrations.

**2. Connect your Kernel key**

Click Connect, select kernel, and paste your API key into the API Key field. Guild sends the key as a bearer token in the Authorization header on every request.

**3. Scope the credential**

Choose account-wide, one workspace, a single member, or a dedicated agent scope. See [Credentials](https://docs.guild.ai/platform/credentials.md) for details on each scope and how Guild resolves which credential to use.

## Why Kernel access needs governing

Kernel tools can create and delete browser sessions, execute arbitrary Playwright code, and read clipboard contents. Without rules, any agent using the credential can run any of these operations. [Credential policies](https://docs.guild.ai/platform/credential-policies.md) let you write ALLOW and DENY rules that Guild's credential proxy enforces before a request leaves Guild. You can restrict specific operations by name or glob pattern, scope rules to individual agents or workspaces, and limit HTTP methods to block mutating calls.

Guild stores the Kernel API key server-side and injects it after the policy check passes. Agent code never sees the key. You can scope a credential to one workspace, one member, or a single agent so that sessions created by an automation pipeline stay separate from those used in development. Guild's credential proxy enforces every policy check; agents cannot bypass it.

## About the Kernel integration

Agents can create and manage cloud browser sessions, including browser pools and reusable profiles that persist state across sessions. They can execute Playwright scripts, run JavaScript in a persistent runtime, and perform low-level computer actions such as clicking, typing, scrolling, and dragging. Agents can also record and replay browser sessions for auditing or debugging. The integration is `guildai~kernel`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Connect Kernel**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **kernel**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { KernelTools } from "@guildai-services/guildai~kernel"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with Kernel.",
  tools: { ...KernelTools },
})
```

### Selecting specific tools

Tools are named with the `kernel_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~kernel`:

> [accordion] All 29 tools
>
> | Tool | What it does |
> | - | - |
> | `kernel_acquire_from_browser_pool_by_id_or_name` | Long-polling endpoint to acquire a browser from the pool. |
> | `kernel_batch_computer_action` | Send an array of computer actions to execute in order on the browser instance. |
> | `kernel_click_mouse` | Kernel returns an empty body. |
> | `kernel_delete_browsers_by_id_or_name` | Delete a browser session by ID or name |
> | `kernel_delete_profile_by_id_or_name` | Delete a profile by its ID or by its name. |
> | `kernel_drag_mouse` | Kernel returns an empty body. |
> | `kernel_execute_browser_repl` | Execute JavaScript in a persistent Node.js runtime inside the browser VM. |
> | `kernel_execute_playwright_code` | Execute arbitrary Playwright code in a fresh execution context against the browser. |
> | `kernel_get_auth_context` | Returns the authenticated principal, organization, credential scope, and effective request scope. |
> | `kernel_get_browser_pools` | List browser pools in the resolved project. |
> | `kernel_get_browsers` | List all browser sessions with pagination support. |
> | `kernel_get_browsers_by_id_or_name` | Get information about a browser session. |
> | `kernel_get_mouse_position` | Get the current mouse cursor position on the browser instance |
> | `kernel_get_profile_by_id_or_name` | Retrieve details for a single profile by its ID or name. |
> | `kernel_get_profiles` | List profiles with optional filtering and pagination. |
> | `kernel_list_browsers_replays` | List all replays for the specified browser session. |
> | `kernel_move_mouse` | Kernel returns an empty body. |
> | `kernel_patch_browsers_by_id_or_name` | Update a browser session. |
> | `kernel_post_browsers` | Create a new browser session from within an action. |
> | `kernel_post_profiles` | Create a browser profile that can be used to load state into future browser sessions. |
> | `kernel_press_key` | Kernel returns an empty body. |
> | `kernel_read_clipboard` | Read text from the clipboard on the browser instance |
> | `kernel_release_to_browser_pool_by_id_or_name` | Release a browser back to the pool, optionally recreating the browser instance. |
> | `kernel_scroll` | Kernel returns an empty body. |
> | `kernel_set_cursor` | Set cursor visibility |
> | `kernel_start_browser_replay_recording` | Start recording the browser session and return a replay ID. |
> | `kernel_stop_browser_replay_recording` | Stop the specified replay recording and persist the video. |
> | `kernel_type_text` | Kernel returns an empty body. |
> | `kernel_write_clipboard` | Kernel returns an empty body. |

## Frequently asked questions

> [accordion] Can an agent trigger actions when a browser session changes state?
>
> No. The Kernel catalog entry lists no webhook events, so the integration has no event-based triggers. Agents must poll session state using the available session tools.

> [accordion] How do I stop one agent from deleting sessions created by another?
>
> Write a credential policy with a DENY rule for the delete operations and scope it to the agent you want to restrict. Guild's credential proxy enforces the rule before any request reaches Kernel. See [Credential policies](https://docs.guild.ai/platform/credential-policies.md).

> [accordion] Where do I connect my Kernel API key?
>
> Go to Access & setup > Credentials, click Connect, select kernel, and paste your key. You can scope it to the whole account, one workspace, yourself, or a single agent.

> [accordion] Can I use only some of the Kernel tools in my agent?
>
> Yes. Tools use the kernel\_ prefix. Use pick() from the Guild Agent SDK to include only the tools your agent needs, as shown in the [tool sets docs](https://docs.guild.ai/sdk/tools.md).

## Put a governed agent on Kernel cloud browsers today

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use Kernel.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect Kernel to your first agent.

## Related

**Also runs on Guild:** [Browserbase](https://docs.guild.ai/integrations/browserbase.md) · [Cloudflare](https://docs.guild.ai/integrations/cloudflare-openapi.md) · [Firecrawl](https://docs.guild.ai/integrations/firecrawl.md) · [Pinecone](https://docs.guild.ai/integrations/pinecone.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)
