diff --git a/apps/deploy.mdx b/apps/deploy.mdx index 1e411963..e574db30 100644 --- a/apps/deploy.mdx +++ b/apps/deploy.mdx @@ -1,5 +1,7 @@ --- -title: "Deploying" +title: "Deploy an App" +sidebarTitle: "Deploy" +description: "Deploy your app to KERNEL, set environment variables, and pass secrets" --- Kernel's app deployment process is as simple as it is fast. There are no configuration files to manage or complex CI/CD pipelines. @@ -94,6 +96,87 @@ const client = new Kernel({ apiKey: process.env.MY_KERNEL_API_KEY }); Now the API calls your app makes go out as your key. The deployment key stays in place for Kernel's own use — running the invocation and reporting its result — so your key only needs permissions for the calls you actually make. +## Secrets + +Pass API keys and other secrets as [environment variables](#environment-variables) when you deploy, with `--env` or `--env-file`. Then read them in your app: + + +```typescript TypeScript +import Anthropic from "@anthropic-ai/sdk"; +import OpenAI from "openai"; + +app.action('ai-action', async (ctx: KernelContext) => { + // Access API keys from environment variables + const anthropic = new Anthropic({ + apiKey: process.env.ANTHROPIC_API_KEY, + }); + + const openai = new OpenAI({ + apiKey: process.env.OPENAI_API_KEY, + }); + + // Use the clients... +}); +``` + +```python Python +import os +from anthropic import Anthropic +from openai import OpenAI + +@app.action("ai-action") +async def ai_action(ctx: KernelContext): + # Access API keys from environment variables + anthropic = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY"), + ) + + openai = OpenAI( + api_key=os.environ.get("OPENAI_API_KEY"), + ) + + # Use the clients... +``` + + +### Per-invocation secrets + +For use cases where different API keys are needed per invocation (such as platforms using end-user keys), pass the secrets at runtime using the [payload parameter](/apps/invoke#payload-parameter). + +Use encryption standards in your app to protect sensitive data. + + +```typescript TypeScript +import OpenAI from "openai"; + +app.action('ai-action', async (ctx: KernelContext, payload) => { + // Decrypt the API key passed at runtime + const apiKey = decrypt(payload.encryptedApiKey); + + const openai = new OpenAI({ + apiKey: apiKey, + }); + + // Use the client with the user's API key... +}); +``` + +```python Python +from openai import OpenAI + +@app.action("ai-action") +async def ai_action(ctx: KernelContext, payload): + # Decrypt the API key passed at runtime + api_key = decrypt(payload["encryptedApiKey"]) + + openai = OpenAI( + api_key=api_key, + ) + + # Use the client with the user's API key... +``` + + ## Deployment notes - **The dependency manifest (`package.json` for JS/TS, `pyproject.toml` for Python) must be present in the root directory of your project.** diff --git a/apps/develop.mdx b/apps/develop.mdx index f572fac1..a77cdf3e 100644 --- a/apps/develop.mdx +++ b/apps/develop.mdx @@ -1,5 +1,7 @@ --- -title: "Developing" +title: "Develop an App" +sidebarTitle: "Develop" +description: "Build an app with actions that run co-located with KERNEL browsers" --- In addition to our browser API, Kernel provides a code execution platform for deploying and invoking code. Typically, Kernel's code execution platform is used for deploying and invoking browser automations or web agents. diff --git a/apps/invoke.mdx b/apps/invoke.mdx index 6be6b018..424740ba 100644 --- a/apps/invoke.mdx +++ b/apps/invoke.mdx @@ -1,5 +1,7 @@ --- -title: "Invoking" +title: "Invoke an App" +sidebarTitle: "Invoke" +description: "Run an app action from the API or CLI, pass a payload, and stop a running invocation" --- ## Via API @@ -154,4 +156,67 @@ See [here](/apps/develop#parameters) to learn how to access the payload in your If your action specifies a [return value](/apps/develop#return-values), the invocation returns its value once it completes. (The Kernel CLI uses asynchronous invocations under the hood) + +## Stop an invocation + +You can terminate an invocation that's running. This is useful for stopping automations or agents stuck in an infinite loop. + + +Terminating an invocation also destroys any browsers associated with it. + + +### Via API +You can stop an invocation by setting its status to `failed`. This will cancel the invocation and mark it as terminated. + + +```typescript Typescript/Javascript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); + +const invocation = await kernel.invocations.update('invocation_id', { + status: 'failed', + output: JSON.stringify({ error: 'Invocation cancelled by user' }), +}); +``` + +```python Python +from kernel import Kernel + +kernel = Kernel() +invocation = kernel.invocations.update( + id="invocation_id", + status="failed", + output='{"error":"Invocation cancelled by user"}', +) +``` + +```go Go +package main + +import ( + "context" + + "github.com/kernel/kernel-go-sdk" +) + +func main() { + ctx := context.Background() + client := kernel.NewClient() + + invocation, err := client.Invocations.Update(ctx, "invocation_id", kernel.InvocationUpdateParams{ + Status: kernel.InvocationUpdateParamsStatusFailed, + Output: kernel.String(`{"error":"Invocation cancelled by user"}`), + }) + if err != nil { + panic(err) + } + _ = invocation +} +``` + + +### Via CLI +Use `ctrl-c` in the terminal tab where you launched the invocation. + App invocations accrue compute usage separately from any browsers they create. See the [pricing FAQ](/info/pricing#faq) for how app invocations are charged. diff --git a/apps/logs.mdx b/apps/logs.mdx index 13454391..4995db06 100644 --- a/apps/logs.mdx +++ b/apps/logs.mdx @@ -1,5 +1,7 @@ --- -title: "Logs" +title: "Invocation Logs" +sidebarTitle: "Logs" +description: "Stream an invocation's logs from the API or CLI" --- ## Via API diff --git a/apps/secrets.mdx b/apps/secrets.mdx deleted file mode 100644 index 6b20afbf..00000000 --- a/apps/secrets.mdx +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: "Secrets" ---- - -There are multiple ways to pass secrets and API keys to your Kernel app: - -## 1. Deployment environment variables - -Deploy your app with secrets as [environment variables](/apps/deploy#environment-variables). Your app can then access them at runtime. - -You can set environment variables in two ways: - -- **`--env` flag**: Pass individual key-value pairs directly in the command -- **`--env-file` flag**: Load variables from a `.env` file - -```bash -# Using --env flag for individual variables -kernel deploy my_app.ts --env OPENAI_API_KEY=sk-... --env ANTHROPIC_API_KEY=sk-ant-... - -# Using --env-file to load from a file -kernel deploy my_app.ts --env-file .env - -# Combine both approaches -kernel deploy my_app.ts --env-file .env --env OPENAI_API_KEY=sk-... -``` - -Then access the variables in your app: - - -```typescript TypeScript -import Anthropic from "@anthropic-ai/sdk"; -import OpenAI from "openai"; - -app.action('ai-action', async (ctx: KernelContext) => { - // Access API keys from environment variables - const anthropic = new Anthropic({ - apiKey: process.env.ANTHROPIC_API_KEY, - }); - - const openai = new OpenAI({ - apiKey: process.env.OPENAI_API_KEY, - }); - - // Use the clients... -}); -``` - -```python Python -import os -from anthropic import Anthropic -from openai import OpenAI - -@app.action("ai-action") -async def ai_action(ctx: KernelContext): - # Access API keys from environment variables - anthropic = Anthropic( - api_key=os.environ.get("ANTHROPIC_API_KEY"), - ) - - openai = OpenAI( - api_key=os.environ.get("OPENAI_API_KEY"), - ) - - # Use the clients... -``` - - -## 2. Runtime variables - -For use cases where different API keys are needed per invocation (such as platforms using end-user keys), pass the secrets at runtime using the [payload parameter](/apps/invoke#payload-parameter). - -Use encryption standards in your app to protect sensitive data. - - -```typescript TypeScript -import OpenAI from "openai"; - -app.action('ai-action', async (ctx: KernelContext, payload) => { - // Decrypt the API key passed at runtime - const apiKey = decrypt(payload.encryptedApiKey); - - const openai = new OpenAI({ - apiKey: apiKey, - }); - - // Use the client with the user's API key... -}); -``` - -```python Python -from openai import OpenAI - -@app.action("ai-action") -async def ai_action(ctx: KernelContext, payload): - # Decrypt the API key passed at runtime - api_key = decrypt(payload["encryptedApiKey"]) - - openai = OpenAI( - api_key=api_key, - ) - - # Use the client with the user's API key... -``` - \ No newline at end of file diff --git a/apps/status.mdx b/apps/status.mdx index 21a81988..658bfb10 100644 --- a/apps/status.mdx +++ b/apps/status.mdx @@ -1,5 +1,7 @@ --- -title: "Status" +title: "Invocation Status" +sidebarTitle: "Status" +description: "Follow an invocation's status by streaming or polling" --- Once you've [deployed](/apps/deploy) an app and invoked it, you can monitor its status using streaming for real-time updates or polling for periodic checks. diff --git a/apps/stop.mdx b/apps/stop.mdx deleted file mode 100644 index da53a560..00000000 --- a/apps/stop.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "Stopping" ---- - -You can terminate an invocation that's running. This is useful for stopping automations or agents stuck in an infinite loop. - - -Terminating an invocation also destroys any browsers associated with it. - - -## Via API -You can stop an invocation by setting its status to `failed`. This will cancel the invocation and mark it as terminated. - - -```typescript Typescript/Javascript -import Kernel from '@onkernel/sdk'; - -const kernel = new Kernel(); - -const invocation = await kernel.invocations.update('invocation_id', { - status: 'failed', - output: JSON.stringify({ error: 'Invocation cancelled by user' }), -}); -``` - -```python Python -from kernel import Kernel - -kernel = Kernel() -invocation = kernel.invocations.update( - id="invocation_id", - status="failed", - output='{"error":"Invocation cancelled by user"}', -) -``` - -```go Go -package main - -import ( - "context" - - "github.com/kernel/kernel-go-sdk" -) - -func main() { - ctx := context.Background() - client := kernel.NewClient() - - invocation, err := client.Invocations.Update(ctx, "invocation_id", kernel.InvocationUpdateParams{ - Status: kernel.InvocationUpdateParamsStatusFailed, - Output: kernel.String(`{"error":"Invocation cancelled by user"}`), - }) - if err != nil { - panic(err) - } - _ = invocation -} -``` - - -## Via CLI -Use `ctrl-c` in the terminal tab where you launched the invocation. diff --git a/auth/configuration.mdx b/auth/configuration.mdx index e90ad981..e23f28af 100644 --- a/auth/configuration.mdx +++ b/auth/configuration.mdx @@ -6,11 +6,483 @@ description: "Shared options for managed auth connections, regardless of integra Managed Auth connections use the same configuration whether you collect credentials through the [Hosted UI](/auth/hosted-ui), the [React component](/auth/react), or the [programmatic flow](/auth/programmatic). These options apply to the initial login, every background health check, and each automatic reauthentication attempt. -## Credentials and Auto-Reauth +## Credentials and auto-reauth by default, KERNEL saves durable credential fields after a successful login. these can support eligible automatic reauthentication attempts, including totp codes generated from an available secret. submitted one-time codes aren't saved and don't provide access to future codes. if a later login requires user input, your application must start a new interactive login. -To opt out of credential saving, set `save_credentials: false` when creating the connection. See [Credentials](/auth/credentials) for configuration examples. +To opt out of credential saving, set `save_credentials: false` when creating the connection. + +credentials let you store login information securely. KERNEL can attempt automatic reauthentication for eligible flows using stored credentials, including totp codes generated from an available secret. saving credentials or completing an interactive login doesn't guarantee unattended reauthentication. supplying a one-time code doesn't give KERNEL the ability to obtain future codes. if a site requires user input, start a new [interactive login](/auth/connection-lifecycle#flows-that-need-input-a-choice-or-approval). + +There are three ways to provide credentials: +- **Automatically save during login** — Capture credentials directly from the user when they log in via [Hosted UI](/auth/hosted-ui) or [Programmatic](/auth/programmatic) +- **Pre-store in Kernel** — Create credentials before login for supported headless authentication flows +- **Connect 1Password** — Use credentials from your existing 1Password vaults + + + Connect your 1Password vaults to automatically use existing credentials with Managed Auth. Credentials are automatically matched by domain. + + +### Save credentials during login + +By default, Kernel saves durable credential fields entered during login so they can be used for eligible reauthentication attempts. No extra parameters are needed: + + +```typescript TypeScript +const login = await kernel.auth.connections.login(auth.id); +``` + +```python Python +login = await kernel.auth.connections.login(auth.id) +``` + +```go Go +login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{}) +if err != nil { + panic(err) +} +_ = login +``` + + +Once saved, the browser profile reuses its authenticated session until the site expires it. For supported credential-based flows, Kernel can then reauthenticate with the stored values. Credentials are updated after every successful login. Submitted one-time codes aren't saved; Kernel generates TOTP codes from a stored `totp_secret`. + +To opt out of credential saving, set `save_credentials: false` when creating the connection: + + +```typescript TypeScript +const auth = await kernel.auth.connections.create({ + domain: 'example.com', + profile_name: 'my-profile', + save_credentials: false, +}); +``` + +```python Python +auth = await kernel.auth.connections.create( + domain="example.com", + profile_name="my-profile", + save_credentials=False, +) +``` + +```go Go +auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{ + ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ + Domain: "example.com", + ProfileName: "my-profile", + SaveCredentials: kernel.Bool(false), + }, +}) +if err != nil { + panic(err) +} +_ = auth +``` + + +### Pre-store credentials + +For credential-based flows that you want to run without user input, create credentials upfront: + + +```typescript TypeScript +const credential = await kernel.credentials.create({ + name: 'my-netflix-login', + domain: 'netflix.com', + values: { + email: 'user@netflix.com', + password: 'secretpassword123', + }, +}); +``` + +```python Python +credential = await kernel.credentials.create( + name="my-netflix-login", + domain="netflix.com", + values={ + "email": "user@netflix.com", + "password": "secretpassword123", + }, +) +``` + +```go Go +credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{ + CreateCredentialRequest: kernel.CreateCredentialRequestParam{ + Name: "my-netflix-login", + Domain: "netflix.com", + Values: map[string]string{ + "email": "user@netflix.com", + "password": "secretpassword123", + }, + }, +}) +if err != nil { + panic(err) +} +_ = credential +``` + + +Then link the credential when creating a connection: + + +```typescript TypeScript +const auth = await kernel.auth.connections.create({ + domain: 'netflix.com', + profile_name: 'my-profile', + credential: { name: credential.name }, +}); + +// Start login with stored credentials +const login = await kernel.auth.connections.login(auth.id); +``` + +```python Python +auth = await kernel.auth.connections.create( + domain="netflix.com", + profile_name="my-profile", + credential={"name": credential.name}, +) + +# Start login with stored credentials +login = await kernel.auth.connections.login(auth.id) +``` + +```go Go +auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{ + ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ + Domain: "netflix.com", + ProfileName: "my-profile", + Credential: kernel.ManagedAuthCreateRequestCredentialParam{ + Name: kernel.String(credential.Name), + }, + }, +}) +if err != nil { + panic(err) +} + +// Start login with stored credentials +login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{}) +if err != nil { + panic(err) +} +_ = login +``` + + +#### 2FA with TOTP + +For sites with authenticator app 2FA, include `totp_secret` so KERNEL can generate a fresh code during automatic login and reauthentication. Supply a base32 secret of 16–128 characters or an `otpauth://totp/` provisioning URI. The default is SHA1, 6 digits, and a 30-second period. If the authenticator uses different settings, provide `totp_algorithm` (`SHA1`, `SHA256`, or `SHA512`), `totp_digits` (6–9), and `totp_period` (15–300 seconds): + + +```typescript TypeScript +const credential = await kernel.credentials.create({ + name: 'my-login', + domain: 'github.com', + values: { + username: 'my-username', + password: 'my-password', + }, + totp_secret: 'JBSWY3DPEHPK3PXP', + totp_algorithm: 'SHA512', + totp_digits: 8, + totp_period: 60, +}); +``` + +```python Python +credential = await kernel.credentials.create( + name="my-login", + domain="github.com", + values={ + "username": "my-username", + "password": "my-password", + }, + totp_secret="JBSWY3DPEHPK3PXP", + totp_algorithm="SHA512", + totp_digits=8, + totp_period=60, +) +``` + +```go Go +credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{ + CreateCredentialRequest: kernel.CreateCredentialRequestParam{ + Name: "my-login", + Domain: "github.com", + Values: map[string]string{ + "username": "my-username", + "password": "my-password", + }, + TotpSecret: kernel.String("JBSWY3DPEHPK3PXP"), + TotpAlgorithm: kernel.CreateCredentialRequestTotpAlgorithmSha512, + TotpDigits: kernel.Int(8), + TotpPeriod: kernel.Int(60), + }, +}) +if err != nil { + panic(err) +} +_ = credential +``` + + +The examples use typed fields available in TypeScript, Python, and Go SDK v0.116.0 or later. You can also pass an `otpauth://totp/` provisioning URI as `totp_secret`. + +- URI parameters override explicit settings. If a parameter is missing, the API uses its explicit field, then the default. +- Replacing a URI resets omitted settings to defaults. Rotating a raw secret preserves stored settings unless you send new values. +- The API stores only the normalized seed, never the URI label or issuer. +- A code's length follows `totp_digits`; don't assume six digits when reading `totp_code` or calling `totpCode()`. + +#### SSO / OAuth + +For sites with "Sign in with Google/GitHub/Microsoft", set `sso_provider` so Kernel can select the matching SSO route. Automatic completion depends on the provider's login requirements. + +Common SSO provider domains (Google, Microsoft, Okta, Auth0, GitHub, etc.) are allowed by default, so you don't need to add them to `allowed_domains`: + + +```typescript TypeScript +const credential = await kernel.credentials.create({ + name: 'my-google-login', + domain: 'accounts.google.com', + sso_provider: 'google', + values: { + email: 'user@gmail.com', + password: 'password', + }, +}); + +const auth = await kernel.auth.connections.create({ + domain: 'target-site.com', + profile_name: 'my-profile', + credential: { name: credential.name }, +}); +``` + +```python Python +credential = await kernel.credentials.create( + name="my-google-login", + domain="accounts.google.com", + sso_provider="google", + values={ + "email": "user@gmail.com", + "password": "password", + }, +) + +auth = await kernel.auth.connections.create( + domain="target-site.com", + profile_name="my-profile", + credential={"name": credential.name}, +) +``` + +```go Go +credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{ + CreateCredentialRequest: kernel.CreateCredentialRequestParam{ + Name: "my-google-login", + Domain: "accounts.google.com", + SSOProvider: kernel.String("google"), + Values: map[string]string{ + "email": "user@gmail.com", + "password": "password", + }, + }, +}) +if err != nil { + panic(err) +} + +auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{ + ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ + Domain: "target-site.com", + ProfileName: "my-profile", + Credential: kernel.ManagedAuthCreateRequestCredentialParam{ + Name: kernel.String(credential.Name), + }, + }, +}) +if err != nil { + panic(err) +} +_ = auth +``` + + +### Partial credentials + +Credentials don't need to contain every field required by the login form. You can store what you have and collect the necessary fields from the user. `auth.connections.login()` pauses for missing values. + +As an example, the below credential has email + TOTP secret stored (and automatically handled), but no password. The password is dynamically collected from the user using Kernel's Hosted UI or your Programmatic flow: + + +```typescript TypeScript +const credential = await kernel.credentials.create({ + name: 'my-login', + domain: 'example.com', + values: { email: 'user@example.com' }, // No password + totp_secret: 'JBSWY3DPEHPK3PXP', +}); + +const auth = await kernel.auth.connections.create({ + domain: 'example.com', + profile_name: 'my-profile', + credential: { name: credential.name }, +}); + +const login = await kernel.auth.connections.login(auth.id); + +// Stream state changes and submit the missing password +const authEvents = await kernel.auth.connections.follow(auth.id); +for await (const event of authEvents) { + const passwordField = event.fields?.find(field => field.ref === 'password'); + if ( + event.event === 'managed_auth_state' && + event.flow_step === 'AWAITING_INPUT' && + event.interaction_id && + passwordField + ) { + // Only password is pending; email is filled from the stored credential. + await kernel.auth.connections.submit(auth.id, { + interaction_id: event.interaction_id, + field_values: { [passwordField.id]: 'user-provided-password' }, + }); + } +} +// TOTP auto-submitted from credential → SUCCESS +``` + +```python Python +credential = await kernel.credentials.create( + name="my-login", + domain="example.com", + values={"email": "user@example.com"}, # No password + totp_secret="JBSWY3DPEHPK3PXP", +) + +auth = await kernel.auth.connections.create( + domain="example.com", + profile_name="my-profile", + credential={"name": credential.name}, +) + +login = await kernel.auth.connections.login(auth.id) + +# Stream state changes and submit the missing password +auth_events = await kernel.auth.connections.follow(auth.id) +async for event in auth_events: + password_field = next( + (field for field in (event.fields or []) if field.ref == "password"), + None, + ) + if ( + event.event == "managed_auth_state" + and event.flow_step == "AWAITING_INPUT" + and event.interaction_id + and password_field + ): + # Only password is pending; email is filled from the stored credential. + await kernel.auth.connections.submit( + auth.id, + interaction_id=event.interaction_id, + field_values={password_field.id: "user-provided-password"}, + ) +# TOTP auto-submitted from credential → SUCCESS +``` + +```go Go +credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{ + CreateCredentialRequest: kernel.CreateCredentialRequestParam{ + Name: "my-login", + Domain: "example.com", + Values: map[string]string{ + "email": "user@example.com", // No password + }, + TotpSecret: kernel.String("JBSWY3DPEHPK3PXP"), + }, +}) +if err != nil { + panic(err) +} + +auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{ + ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ + Domain: "example.com", + ProfileName: "my-profile", + Credential: kernel.ManagedAuthCreateRequestCredentialParam{ + Name: kernel.String(credential.Name), + }, + }, +}) +if err != nil { + panic(err) +} + +login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{}) +if err != nil { + panic(err) +} +_ = login + +// Stream state changes and submit the missing password +authEvents := client.Auth.Connections.FollowStreaming(ctx, auth.ID) +for authEvents.Next() { + event := authEvents.Current() + if event.Event != "managed_auth_state" || event.FlowStep != "AWAITING_INPUT" || event.InteractionID == "" { + continue + } + for _, field := range event.Fields { + if field.Ref != "password" { + continue + } + // Only password is pending; email is filled from the stored credential. + _, err := client.Auth.Connections.Submit(ctx, auth.ID, kernel.AuthConnectionSubmitParams{ + SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{ + InteractionID: kernel.String(event.InteractionID), + FieldValues: map[string]string{ + field.ID: "user-provided-password", + }, + }, + }) + if err != nil { + panic(err) + } + break + } +} +if err := authEvents.Err(); err != nil { + panic(err) +} +// TOTP auto-submitted from credential → SUCCESS +``` + + +This is useful when you want to: +- Store TOTP secrets but have users enter their password each time +- Pre-fill username/email but collect password at runtime +- Merge user-provided values into an existing credential automatically on successful login + +### Credential security + +| Feature | Description | +|---------|-------------| +| **Encrypted at rest** | Values encrypted using per-organization keys | +| **Write-only** | Values cannot be retrieved via API after creation | +| **Never logged** | Values are never written to logs | +| **Never shared** | Values are never passed to LLMs | +| **Isolated execution** | Authentication runs in isolated browser environments | + +### Credential notes + +- The `values` object is flexible and can be used to store whatever fields the login form needs (`email`, `username`, `company_id`, etc.) +- Deleting a credential unlinks it from associated connections so they can no longer auto-authenticate +- Use one credential per account. We recommend creating separate credentials for different user accounts + +### Automatic reauthentication Automatic re-authentication is gated by two boolean flags that both default to `true`: @@ -60,7 +532,7 @@ Automatic reauthentication requires a previously successful login and saved cred If Kernel can't complete an automatic attempt, the connection transitions to `NEEDS_AUTH` so you can start a new login. -## Custom Login URL +## Custom login URL If the site's login page isn't at the default location, specify it when creating the connection: @@ -96,7 +568,7 @@ _ = auth ``` -## Browser Region +## Browser region Set `browser.region` to choose where Managed Auth runs the connection's initial login, health checks, and automatic reauthentication. Choose from `us-east`, `eu-west`, and `ap-southeast`. Region selection is available on [Start-Up and Enterprise plans](/info/pricing); omitted values default to `us-east`. @@ -167,7 +639,7 @@ _ = login Browser placement and proxy location are independent. `browser.region` chooses where the browser runs; the connection's [proxy](/proxies/overview) controls the exit IP that websites see. Regional browsers don't provide a data residency guarantee. See [Regional Browsers](/browsers/regions) for storage and processing details. -## SSO/OAuth Support +## SSO/OAuth support Managed Auth supports common "Sign in with Google/GitHub/Microsoft" flows. The user completes the OAuth flow with the provider, and Kernel saves the authenticated session to the profile. Automatic reauthentication depends on the provider's login requirements. See [Can this connection auto-reauth?](/auth/connection-lifecycle#can-this-connection-auto-reauth) for how Kernel determines eligibility. @@ -207,7 +679,7 @@ _ = auth ``` -## Custom Proxy +## Custom proxy Pin the auth flow to a specific [proxy](/proxies/overview) so logins, health checks, and automatic re-authentications all egress through that proxy. This is useful for sites that allowlist IPs, geo-pin sessions, or treat IP changes as a fraud signal. @@ -328,7 +800,7 @@ _ = login ``` -## Record Sessions for Debugging +## Record sessions for debugging Set `record_session: true` to capture a [replay](/browsers/replays) of every browser session tied to the connection — initial logins, background health checks, and automatic re-authentications. The entire browser session is recorded. @@ -393,7 +865,7 @@ _ = login Managed auth recordings are subject to the same retention rules as other session replay recordings. Each managed auth session row stores its own `replay_id` for the recording captured during that session. -## Post-Login URL +## Post-login URL After successful authentication, `post_login_url` will be set to the page where the login landed. Use this to start your automation from the right place: @@ -433,7 +905,7 @@ if managedAuth.PostLoginURL != "" { ``` -## Updating a Connection +## Updating a connection After creating a connection, you can update its configuration with `auth.connections.update`: diff --git a/auth/connection-lifecycle.mdx b/auth/connection-lifecycle.mdx index 5cb4904a..3b194279 100644 --- a/auth/connection-lifecycle.mdx +++ b/auth/connection-lifecycle.mdx @@ -226,7 +226,7 @@ See the [API reference](https://kernel.sh/docs/api-reference/managed-auth/start- ### Recovering -- **`credentials_invalid`** — Update the linked [credential](/auth/credentials) and call `.login()` to re-run the flow. When the site identifies which field it rejected during an interactive login, Kernel asks for a corrected value in place — see [replacing a rejected credential](/auth/programmatic#replacing-a-rejected-credential). +- **`credentials_invalid`** — Update the linked [credential](/auth/configuration#credentials-and-auto-reauth) and call `.login()` to re-run the flow. When the site identifies which field it rejected during an interactive login, Kernel asks for a corrected value in place — see [replacing a rejected credential](/auth/programmatic#replacing-a-rejected-credential). - **`totp_code_rejected`** — Retry with a code from a new TOTP window. If independently generated codes keep failing, reconnect the account and update its TOTP secret. One rejected code does not prove that the saved secret is stale. - **`totp_required` / `sms_code_required` / `email_code_required`** — Start an interactive login and provide the requested code. Add a TOTP secret to the linked credential to make future authenticator-code challenges automatic. - **`account_choice_required` / `customer_input_required` / `external_action_required`** — Start an interactive login and complete the choice, field, or external approval. Kernel does not guess an identity or trigger notification-producing steps during unattended reauth. @@ -274,5 +274,5 @@ To record every auth session on the connection (logins, health checks, and reaut ## See also - [Connection Configuration](/auth/configuration) — `health_check_interval`, `proxy`, `record_session`, and other shared options -- [Credentials](/auth/credentials) — what gets stored and how it powers auto-reauth +- [Credentials](/auth/configuration#credentials-and-auto-reauth) — what gets stored and how it powers auto-reauth - [FAQ](/auth/faq) — quick answers to common questions diff --git a/auth/credentials.mdx b/auth/credentials.mdx deleted file mode 100644 index 2f253f3a..00000000 --- a/auth/credentials.mdx +++ /dev/null @@ -1,474 +0,0 @@ ---- -title: "Managed Auth Credentials" -description: "Use stored credentials for login and eligible automatic reauthentication attempts" ---- - -credentials let you store login information securely. KERNEL can attempt automatic reauthentication for eligible flows using stored credentials, including totp codes generated from an available secret. saving credentials or completing an interactive login doesn't guarantee unattended reauthentication. supplying a one-time code doesn't give KERNEL the ability to obtain future codes. if a site requires user input, start a new [interactive login](/auth/connection-lifecycle#flows-that-need-input-a-choice-or-approval). - -**There are three ways to provide credentials:** -- **Automatically save during login** — Capture credentials directly from the user when they log in via [Hosted UI](/auth/hosted-ui) or [Programmatic](/auth/programmatic) -- **Pre-store in Kernel** — Create credentials before login for supported headless authentication flows -- **Connect 1Password** — Use credentials from your existing 1Password vaults - - - Connect your 1Password vaults to automatically use existing credentials with Managed Auth. Credentials are automatically matched by domain. - - -## Save credentials during login - -By default, Kernel saves durable credential fields entered during login so they can be used for eligible reauthentication attempts. No extra parameters are needed: - - -```typescript TypeScript -const login = await kernel.auth.connections.login(auth.id); -``` - -```python Python -login = await kernel.auth.connections.login(auth.id) -``` - -```go Go -login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{}) -if err != nil { - panic(err) -} -_ = login -``` - - -Once saved, the browser profile reuses its authenticated session until the site expires it. For supported credential-based flows, Kernel can then reauthenticate with the stored values. Credentials are updated after every successful login. Submitted one-time codes aren't saved; Kernel generates TOTP codes from a stored `totp_secret`. - -To opt out of credential saving, set `save_credentials: false` when creating the connection: - - -```typescript TypeScript -const auth = await kernel.auth.connections.create({ - domain: 'example.com', - profile_name: 'my-profile', - save_credentials: false, -}); -``` - -```python Python -auth = await kernel.auth.connections.create( - domain="example.com", - profile_name="my-profile", - save_credentials=False, -) -``` - -```go Go -auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{ - ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ - Domain: "example.com", - ProfileName: "my-profile", - SaveCredentials: kernel.Bool(false), - }, -}) -if err != nil { - panic(err) -} -_ = auth -``` - - -## Pre-store credentials - -For credential-based flows that you want to run without user input, create credentials upfront: - - -```typescript TypeScript -const credential = await kernel.credentials.create({ - name: 'my-netflix-login', - domain: 'netflix.com', - values: { - email: 'user@netflix.com', - password: 'secretpassword123', - }, -}); -``` - -```python Python -credential = await kernel.credentials.create( - name="my-netflix-login", - domain="netflix.com", - values={ - "email": "user@netflix.com", - "password": "secretpassword123", - }, -) -``` - -```go Go -credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{ - CreateCredentialRequest: kernel.CreateCredentialRequestParam{ - Name: "my-netflix-login", - Domain: "netflix.com", - Values: map[string]string{ - "email": "user@netflix.com", - "password": "secretpassword123", - }, - }, -}) -if err != nil { - panic(err) -} -_ = credential -``` - - -Then link the credential when creating a connection: - - -```typescript TypeScript -const auth = await kernel.auth.connections.create({ - domain: 'netflix.com', - profile_name: 'my-profile', - credential: { name: credential.name }, -}); - -// Start login with stored credentials -const login = await kernel.auth.connections.login(auth.id); -``` - -```python Python -auth = await kernel.auth.connections.create( - domain="netflix.com", - profile_name="my-profile", - credential={"name": credential.name}, -) - -# Start login with stored credentials -login = await kernel.auth.connections.login(auth.id) -``` - -```go Go -auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{ - ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ - Domain: "netflix.com", - ProfileName: "my-profile", - Credential: kernel.ManagedAuthCreateRequestCredentialParam{ - Name: kernel.String(credential.Name), - }, - }, -}) -if err != nil { - panic(err) -} - -// Start login with stored credentials -login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{}) -if err != nil { - panic(err) -} -_ = login -``` - - -### 2FA with TOTP - -For sites with authenticator app 2FA, include `totp_secret` so KERNEL can generate a fresh code during automatic login and reauthentication. Supply a base32 secret of 16–128 characters or an `otpauth://totp/` provisioning URI. The default is SHA1, 6 digits, and a 30-second period. If the authenticator uses different settings, provide `totp_algorithm` (`SHA1`, `SHA256`, or `SHA512`), `totp_digits` (6–9), and `totp_period` (15–300 seconds): - - -```typescript TypeScript -const credential = await kernel.credentials.create({ - name: 'my-login', - domain: 'github.com', - values: { - username: 'my-username', - password: 'my-password', - }, - totp_secret: 'JBSWY3DPEHPK3PXP', - totp_algorithm: 'SHA512', - totp_digits: 8, - totp_period: 60, -}); -``` - -```python Python -credential = await kernel.credentials.create( - name="my-login", - domain="github.com", - values={ - "username": "my-username", - "password": "my-password", - }, - totp_secret="JBSWY3DPEHPK3PXP", - totp_algorithm="SHA512", - totp_digits=8, - totp_period=60, -) -``` - -```go Go -credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{ - CreateCredentialRequest: kernel.CreateCredentialRequestParam{ - Name: "my-login", - Domain: "github.com", - Values: map[string]string{ - "username": "my-username", - "password": "my-password", - }, - TotpSecret: kernel.String("JBSWY3DPEHPK3PXP"), - TotpAlgorithm: kernel.CreateCredentialRequestTotpAlgorithmSha512, - TotpDigits: kernel.Int(8), - TotpPeriod: kernel.Int(60), - }, -}) -if err != nil { - panic(err) -} -_ = credential -``` - - -The examples use typed fields available in TypeScript, Python, and Go SDK v0.116.0 or later. You can also pass an `otpauth://totp/` provisioning URI as `totp_secret`. - -- URI parameters override explicit settings. If a parameter is missing, the API uses its explicit field, then the default. -- Replacing a URI resets omitted settings to defaults. Rotating a raw secret preserves stored settings unless you send new values. -- The API stores only the normalized seed, never the URI label or issuer. -- A code's length follows `totp_digits`; don't assume six digits when reading `totp_code` or calling `totpCode()`. - -### SSO / OAuth - -For sites with "Sign in with Google/GitHub/Microsoft", set `sso_provider` so Kernel can select the matching SSO route. Automatic completion depends on the provider's login requirements. - -Common SSO provider domains (Google, Microsoft, Okta, Auth0, GitHub, etc.) are allowed by default, so you don't need to add them to `allowed_domains`: - - -```typescript TypeScript -const credential = await kernel.credentials.create({ - name: 'my-google-login', - domain: 'accounts.google.com', - sso_provider: 'google', - values: { - email: 'user@gmail.com', - password: 'password', - }, -}); - -const auth = await kernel.auth.connections.create({ - domain: 'target-site.com', - profile_name: 'my-profile', - credential: { name: credential.name }, -}); -``` - -```python Python -credential = await kernel.credentials.create( - name="my-google-login", - domain="accounts.google.com", - sso_provider="google", - values={ - "email": "user@gmail.com", - "password": "password", - }, -) - -auth = await kernel.auth.connections.create( - domain="target-site.com", - profile_name="my-profile", - credential={"name": credential.name}, -) -``` - -```go Go -credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{ - CreateCredentialRequest: kernel.CreateCredentialRequestParam{ - Name: "my-google-login", - Domain: "accounts.google.com", - SSOProvider: kernel.String("google"), - Values: map[string]string{ - "email": "user@gmail.com", - "password": "password", - }, - }, -}) -if err != nil { - panic(err) -} - -auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{ - ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ - Domain: "target-site.com", - ProfileName: "my-profile", - Credential: kernel.ManagedAuthCreateRequestCredentialParam{ - Name: kernel.String(credential.Name), - }, - }, -}) -if err != nil { - panic(err) -} -_ = auth -``` - - -## Partial Credentials - -Credentials don't need to contain every field required by the login form. You can store what you have and collect the necessary fields from the user. `auth.connections.login()` pauses for missing values. - -As an example, the below credential has email + TOTP secret stored (and automatically handled), but no password. The password is dynamically collected from the user using Kernel's Hosted UI or your Programmatic flow: - - -```typescript TypeScript -const credential = await kernel.credentials.create({ - name: 'my-login', - domain: 'example.com', - values: { email: 'user@example.com' }, // No password - totp_secret: 'JBSWY3DPEHPK3PXP', -}); - -const auth = await kernel.auth.connections.create({ - domain: 'example.com', - profile_name: 'my-profile', - credential: { name: credential.name }, -}); - -const login = await kernel.auth.connections.login(auth.id); - -// Stream state changes and submit the missing password -const authEvents = await kernel.auth.connections.follow(auth.id); -for await (const event of authEvents) { - const passwordField = event.fields?.find(field => field.ref === 'password'); - if ( - event.event === 'managed_auth_state' && - event.flow_step === 'AWAITING_INPUT' && - event.interaction_id && - passwordField - ) { - // Only password is pending; email is filled from the stored credential. - await kernel.auth.connections.submit(auth.id, { - interaction_id: event.interaction_id, - field_values: { [passwordField.id]: 'user-provided-password' }, - }); - } -} -// TOTP auto-submitted from credential → SUCCESS -``` - -```python Python -credential = await kernel.credentials.create( - name="my-login", - domain="example.com", - values={"email": "user@example.com"}, # No password - totp_secret="JBSWY3DPEHPK3PXP", -) - -auth = await kernel.auth.connections.create( - domain="example.com", - profile_name="my-profile", - credential={"name": credential.name}, -) - -login = await kernel.auth.connections.login(auth.id) - -# Stream state changes and submit the missing password -auth_events = await kernel.auth.connections.follow(auth.id) -async for event in auth_events: - password_field = next( - (field for field in (event.fields or []) if field.ref == "password"), - None, - ) - if ( - event.event == "managed_auth_state" - and event.flow_step == "AWAITING_INPUT" - and event.interaction_id - and password_field - ): - # Only password is pending; email is filled from the stored credential. - await kernel.auth.connections.submit( - auth.id, - interaction_id=event.interaction_id, - field_values={password_field.id: "user-provided-password"}, - ) -# TOTP auto-submitted from credential → SUCCESS -``` - -```go Go -credential, err := client.Credentials.New(ctx, kernel.CredentialNewParams{ - CreateCredentialRequest: kernel.CreateCredentialRequestParam{ - Name: "my-login", - Domain: "example.com", - Values: map[string]string{ - "email": "user@example.com", // No password - }, - TotpSecret: kernel.String("JBSWY3DPEHPK3PXP"), - }, -}) -if err != nil { - panic(err) -} - -auth, err := client.Auth.Connections.New(ctx, kernel.AuthConnectionNewParams{ - ManagedAuthCreateRequest: kernel.ManagedAuthCreateRequestParam{ - Domain: "example.com", - ProfileName: "my-profile", - Credential: kernel.ManagedAuthCreateRequestCredentialParam{ - Name: kernel.String(credential.Name), - }, - }, -}) -if err != nil { - panic(err) -} - -login, err := client.Auth.Connections.Login(ctx, auth.ID, kernel.AuthConnectionLoginParams{}) -if err != nil { - panic(err) -} -_ = login - -// Stream state changes and submit the missing password -authEvents := client.Auth.Connections.FollowStreaming(ctx, auth.ID) -for authEvents.Next() { - event := authEvents.Current() - if event.Event != "managed_auth_state" || event.FlowStep != "AWAITING_INPUT" || event.InteractionID == "" { - continue - } - for _, field := range event.Fields { - if field.Ref != "password" { - continue - } - // Only password is pending; email is filled from the stored credential. - _, err := client.Auth.Connections.Submit(ctx, auth.ID, kernel.AuthConnectionSubmitParams{ - SubmitFieldsRequest: kernel.SubmitFieldsRequestParam{ - InteractionID: kernel.String(event.InteractionID), - FieldValues: map[string]string{ - field.ID: "user-provided-password", - }, - }, - }) - if err != nil { - panic(err) - } - break - } -} -if err := authEvents.Err(); err != nil { - panic(err) -} -// TOTP auto-submitted from credential → SUCCESS -``` - - -This is useful when you want to: -- Store TOTP secrets but have users enter their password each time -- Pre-fill username/email but collect password at runtime -- Merge user-provided values into an existing credential automatically on successful login - -## Security - -| Feature | Description | -|---------|-------------| -| **Encrypted at rest** | Values encrypted using per-organization keys | -| **Write-only** | Values cannot be retrieved via API after creation | -| **Never logged** | Values are never written to logs | -| **Never shared** | Values are never passed to LLMs | -| **Isolated execution** | Authentication runs in isolated browser environments | - -## Notes - -- The `values` object is flexible and can be used to store whatever fields the login form needs (`email`, `username`, `company_id`, etc.) -- Deleting a credential unlinks it from associated connections so they can no longer auto-authenticate -- Use one credential per account. We recommend creating separate credentials for different user accounts diff --git a/auth/faq.mdx b/auth/faq.mdx index 525ba9ce..360696c4 100644 --- a/auth/faq.mdx +++ b/auth/faq.mdx @@ -61,4 +61,4 @@ See [Reuse one identity across sites](/browsers/profiles/agent-patterns#reuse-on Managed Auth is included on all plans with no per-connection fees. It uses browser sessions for login, health checks, and eligible reauthentication attempts. These count toward your browser usage like any other browser session. -Auth sessions are fast (typically 5-30 seconds each). Kernel monitors session health and can automatically reauthenticate eligible credential-based flows when sessions expire. Most sessions stay valid for days. For example, monitoring 100 auth connections typically costs less than $5/month in browser usage. See [Pricing & Limits](/info/pricing#managed-auth) for details. +Auth sessions are fast (typically 5-30 seconds each). Kernel monitors session health and can automatically reauthenticate eligible credential-based flows when sessions expire. Most sessions stay valid for days. For example, monitoring 100 auth connections typically costs less than $5/month in browser usage. See [Pricing](/info/pricing#faq) for details. diff --git a/auth/fill-from-managed-auth.mdx b/auth/fill-from-managed-auth.mdx index 17d09d47..a31a0278 100644 --- a/auth/fill-from-managed-auth.mdx +++ b/auth/fill-from-managed-auth.mdx @@ -31,7 +31,7 @@ Choose [Fill from Vault](/auth/fill-from-vault) with a Kernel credential item wh ## Requirements -- The connection holds a Kernel credential. Managed Auth saves one by default after a successful login. A connection created with `save_credentials: false` qualifies once you link a [pre-stored credential](/auth/credentials#pre-store-credentials) to it, when creating the connection or by updating it. +- The connection holds a Kernel credential. Managed Auth saves one by default after a successful login. A connection created with `save_credentials: false` qualifies once you link a [pre-stored credential](/auth/configuration#pre-store-credentials) to it, when creating the connection or by updating it. - The connection's credential is stored in Kernel. Connections backed by [1Password](/integrations/1password) keep their values in 1Password and can't back an item. - The connection, the vault, and the browser belong to the same project. @@ -49,7 +49,7 @@ These examples continue in order, using GitHub as the login destination. Set `KE - Wait for the saved credential, not for the connection's status. A connection that's `NEEDS_AUTH` still qualifies as long as it holds a saved credential. If you named the credential yourself, the connection's `credential` field shows it as soon as it's linked, even before it holds any values, so retrieve the [credential](/auth/credentials) and check `has_values` or `has_totp_secret` instead. + Wait for the saved credential, not for the connection's status. A connection that's `NEEDS_AUTH` still qualifies as long as it holds a saved credential. If you named the credential yourself, the connection's `credential` field shows it as soon as it's linked, even before it holds any values, so retrieve the [credential](/auth/configuration#credentials-and-auto-reauth) and check `has_values` or `has_totp_secret` instead. Create a [vault](/vaults/overview) for the user, then create a credential item whose `spec` names the connection, with an optional `description` such as the site name. The item is created `ready`, and `state.fields` lists the field names you can fill. @@ -92,7 +92,7 @@ Reading the item describes the credential without returning any values: -Field names come from the login itself, so read them from `state.fields` instead of assuming them. Each entry carries a `type` of `text`, `email`, `password`, or `totp`. A `totp` entry appears only when the credential has a TOTP secret, such as one stored with `totp_secret` through the [credentials API](/auth/credentials); a Managed Auth login doesn't save one. `fill` writes a code generated with the credential's TOTP settings, never the secret. Entries change when the connection's credential changes, and the item's `version` stays at `1`, so compare `state.fields` rather than `version` to observe changes. +Field names come from the login itself, so read them from `state.fields` instead of assuming them. Each entry carries a `type` of `text`, `email`, `password`, or `totp`. A `totp` entry appears only when the credential has a TOTP secret, such as one stored with `totp_secret` through the [credentials API](/auth/configuration#credentials-and-auto-reauth); a Managed Auth login doesn't save one. `fill` writes a code generated with the credential's TOTP settings, never the secret. Entries change when the connection's credential changes, and the item's `version` stays at `1`, so compare `state.fields` rather than `version` to observe changes. ## Item status @@ -110,7 +110,7 @@ An unavailable item advertises no operations. Managed Auth owns the connection a ## How it differs from a Kernel credential item - There's no collection form and no `collect` operation. Managed Auth collects the login. -- The item can't be edited. Change the credential through Managed Auth, by logging in again or updating the linked [credential](/auth/credentials), and the item picks the change up. +- The item can't be edited. Change the credential through Managed Auth, by logging in again or updating the linked [credential](/auth/configuration#credentials-and-auto-reauth), and the item picks the change up. - Field names and types mirror the saved credential instead of a field list you declare. `wait` doesn't apply, because the item is created ready. - Deleting the item leaves the connection and its credential in place. Deleting the connection or its credential makes the item unavailable. @@ -124,7 +124,7 @@ An unavailable item advertises no operations. Managed Auth owns the connection a Map credential fields to browser inputs and handle completed, failed, or unknown outcomes. - + How Managed Auth saves credentials during login and how to update them. diff --git a/auth/fill-from-vault.mdx b/auth/fill-from-vault.mdx index ef3064ad..093472a7 100644 --- a/auth/fill-from-vault.mdx +++ b/auth/fill-from-vault.mdx @@ -1,5 +1,5 @@ --- -title: "Overview" +title: "Fill from Vault" description: "Collect end-user credentials and inject them into browser forms while controlling the login workflow" --- diff --git a/auth/hosted-ui.mdx b/auth/hosted-ui.mdx index 5b510123..bcb0e6f8 100644 --- a/auth/hosted-ui.mdx +++ b/auth/hosted-ui.mdx @@ -12,7 +12,7 @@ Use the Hosted UI when: ## Getting started -### 1. Create a Connection +### 1. Create a connection A Managed Auth connection saves a domain's authentication state to a [profile](/browsers/profiles) so future browsers can reuse it. You can attach multiple auth connections to the same profile, one per domain. @@ -45,7 +45,7 @@ _ = auth ``` -### 2. Start a Login Session +### 2. Start a login session Start a Managed Auth Session to get the hosted login URL. @@ -67,7 +67,7 @@ _ = login ``` -### 3. Collect Credentials +### 3. Collect credentials Send the user to the hosted login page: @@ -152,7 +152,7 @@ if authenticated { The SSE stream closes automatically when the flow succeeds, fails, expires, or is canceled. The session expires after 20 minutes if not completed, and the flow times out after 10 minutes of waiting for user input. -### 5. Use the Profile +### 5. Use the profile Create browsers with the profile and navigate to the site. The browser loads the authentication state saved during login: @@ -203,7 +203,7 @@ Managed Auth Connections are generated using Kernel's [stealth](/browsers/bot-de -## Complete Example +## Complete example ```typescript TypeScript @@ -420,6 +420,6 @@ func main() { The hosted page redirects to whatever URL you pass. Only set these from your own trusted backend — never let an end user supply them directly. -## Connection Configuration +## Connection configuration Connection-level options — custom login URL, SSO/OAuth, custom proxy, session recording, post-login URL, and updates — apply equally to all integration flows and are documented in [Connection Configuration](/auth/configuration). diff --git a/auth/managed-auth.mdx b/auth/managed-auth.mdx index 8d1a0f4d..4afc1f14 100644 --- a/auth/managed-auth.mdx +++ b/auth/managed-auth.mdx @@ -1,5 +1,6 @@ --- -title: "Overview" +title: "Managed Auth" +sidebarTitle: "Overview" description: "Handle website login, reuse session state, and recover eligible connections automatically" --- @@ -51,7 +52,7 @@ _ = auth A **Managed Auth Session** is the corresponding login flow for the specified connection. Users provide credentials via a KERNEL-hosted page or your own UI. - link a [credential](/auth/credentials) so KERNEL can attempt reauthentication when the connection is eligible. stored credentials alone don't make every flow eligible. + link a [credential](/auth/configuration#credentials-and-auto-reauth) so KERNEL can attempt reauthentication when the connection is eligible. stored credentials alone don't make every flow eligible. ```typescript TypeScript @@ -195,6 +196,21 @@ these steps establish the initial connection. your integration must also handle +## Connection options + +Every connection uses the same options, whichever integration you choose. See [configuration](/auth/configuration) for examples of each. + +| Option | What it does | +| --- | --- | +| [Credentials](/auth/configuration#credentials-and-auto-reauth) | Save login values during the first login, or store them ahead of time, so KERNEL can attempt eligible reauthentication. | +| [Automatic reauthentication](/auth/configuration#automatic-reauthentication) | Run health checks and attempt to reauthenticate eligible connections when a session expires, controlled by `health_checks` and `auto_reauth`. | +| [Custom login URL](/auth/configuration#custom-login-url) | Start the login from a specific page instead of the domain's default. | +| [Browser region](/auth/configuration#browser-region) | Run the login and health checks in the region your browsers use. | +| [SSO and OAuth](/auth/configuration#ssooauth-support) | Support "Sign in with Google, GitHub, or Microsoft" flows. Common identity providers are allowed by default. | +| [Custom proxy](/auth/configuration#custom-proxy) | Send login traffic through a proxy you choose. | +| [Session recording](/auth/configuration#record-sessions-for-debugging) | Record login attempts as replays for debugging. | +| [Post-login URL](/auth/configuration#post-login-url) | Read the page the login landed on, so your automation starts from the right place. | + ## Why Managed Auth? Managed Auth runs **login flows** by navigating login pages, filling credentials, following SSO redirects, and guiding users through additional authentication steps. It saves the resulting session state to a reusable profile. diff --git a/auth/overview.mdx b/auth/overview.mdx index 99893cd2..577f3678 100644 --- a/auth/overview.mdx +++ b/auth/overview.mdx @@ -1,5 +1,6 @@ --- -title: "Overview" +title: "Authentication" +sidebarTitle: "Overview" description: "Choose how your browser agents authenticate and reuse signed-in sessions" --- diff --git a/auth/react.mdx b/auth/react.mdx index 6beaee7f..beecc847 100644 --- a/auth/react.mdx +++ b/auth/react.mdx @@ -19,7 +19,7 @@ bun add @onkernel/managed-auth-react ## Getting started -### 1. Start a Login Session on your backend +### 1. Start a login session on your backend Same as the Hosted UI flow — create a connection and start a login. The login response returns the connection `id` and a one-time `handoff_code`; those are the two values you'll hand to the component on the frontend. @@ -270,7 +270,7 @@ import { Wrap them in `` and `` to inherit the same styling/localization plumbing as the all-in-one component. -## Connection Configuration +## Connection configuration Connection-level options — custom login URL, SSO/OAuth, custom proxy, session recording, post-login URL, and updates — are set on `auth.connections.create` (or later via `auth.connections.update`) and apply equally regardless of which integration flow you use. See [Connection Configuration](/auth/configuration). diff --git a/bots.mdx b/bots.mdx index 49b03d98..48440ddd 100644 --- a/bots.mdx +++ b/bots.mdx @@ -1,5 +1,6 @@ --- -title: "Bots and agents" +title: "KERNEL Bots and Agents" +sidebarTitle: "Verify KERNEL Traffic" description: "Kernel's bots and agents, their purposes, and how to verify them with Web Bot Auth" --- diff --git a/browsers/bot-detection/hcaptcha.mdx b/browsers/bot-detection/hcaptcha.mdx deleted file mode 100644 index f1763b96..00000000 --- a/browsers/bot-detection/hcaptcha.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "hCaptcha" ---- - -Kernel's hCaptcha solver is a beta feature for teams that need help handling hCaptcha challenges in browser automations. - -When enabled for your organization, Kernel can attempt to solve supported hCaptcha challenges automatically from Kernel browsers. This is useful for permitted automation where hCaptcha appears as part of a normal browser workflow, such as QA, account operations, or user-authorized agent tasks. - - -The hCaptcha solver is in beta and isn't enabled for all organizations by default. - - -## Get access - -To use the hCaptcha solver, [contact Kernel support](https://www.kernel.sh/docs/info/support) and ask to have the hCaptcha beta enabled for your organization. - -Include the website or workflow you're testing, your expected volume, and whether you're already using [stealth mode](/browsers/bot-detection/stealth), [profiles](/browsers/profiles), or custom [proxies](/proxies/overview). This helps us confirm the right setup for your use case. diff --git a/browsers/bot-detection/overview.mdx b/browsers/bot-detection/overview.mdx index 44c23a27..63aa5e30 100644 --- a/browsers/bot-detection/overview.mdx +++ b/browsers/bot-detection/overview.mdx @@ -1,5 +1,6 @@ --- -title: "Overview" +title: "Stealth" +sidebarTitle: "Overview" description: "Help your browser agents access websites with anti-detection defaults, stealth mode, proxies, and opt-in Web Bot Auth (WBA)." --- @@ -12,7 +13,7 @@ Under the hood, our browsers are optimized for realistic environments. **Everyth This guide explains how bot detection works at a high level, common pitfalls to avoid, and how Kernel's features can help your automations run reliably. -## How Bot Detection Works +## How bot detection works Most detection systems look for inconsistencies between how a real user's browser behaves and how an automated one does. Common giveaways include: - **IP addresses**: IPs from data centers (AWS, GCP, Azure) @@ -24,11 +25,11 @@ Most detection systems look for inconsistencies between how a real user's browse These systems are heuristic and probabilistic — small mismatches can still trigger blocks. The goal isn't to “beat” detection but rather emulate the real-world conditions of a normal browser session. -## Kernel Features That Help +## KERNEL features that help ### Anti-detection defaults Every Kernel browser launches with anti-detection chrome configuration applied. No setup required. -### [Stealth Mode](/browsers/bot-detection/stealth) +### [Stealth mode](/browsers/bot-detection/stealth) On top of the defaults, stealth mode adds a default ISP proxy and an automatic CAPTCHA solver. Both are opt-out so you can BYO proxy and/or CAPTCHA tooling. ### [Web Bot Auth (WBA)](/browsers/bot-detection/web-bot-auth) @@ -39,27 +40,27 @@ WBA lets your agent sign requests with a verifiable identity. Participating webs ### [Config Registry](/config-registry) Kernel recommended browser and proxy configurations for websites. -### [Configurable Proxies](/proxies/overview) +### [Configurable proxies](/proxies/overview) Bring your own proxy network or use Kernel's managed proxy pool (selectable down to ZIP-code level). If needed, use the same IP to reduce detection and allow for regional testing or QA. ### [Profiles](/browsers/profiles) Profiles persist cookies, local storage, and session data between runs. Combined with a fixed proxy, this mimics a returning user. We recommend using them to persist authenticated states and reduce CAPTCHAs. -### [Browser Pools](/browsers/pools) +### [Browser pools](/browsers/pools) Browser pools let you reuse browsers across multiple visits to the same website, which introduces consistency with respect to the IP address. Since IP addresses are one of the main components of fingerprinting used by modern bot detection systems, browser pools drastically increase your chances of avoiding detection. -### [Playwright Execution API](/browsers/playwright-execution) +### [Playwright execution API](/browsers/playwright-execution) Executes Playwright scripts in the same VM as the browser, ensuring headers, user-agent strings, and environment match. Kernel automatically applies Patchright to remove automation fingerprints, including headless indicators. -### [Computer Controls API](/browsers/computer-controls) +### [Computer controls API](/browsers/computer-controls) Controls the browser without using the Chrome DevTools Protocol (CDP), which can reduce bot detection signals. Emulates native keyboard and mouse input directly at the OS level and includes human-like [bezier curves](/browsers/computer-controls#move-the-mouse) by default. -### [GPU Acceleration](/browsers/gpu-acceleration) +### [GPU acceleration](/browsers/gpu-acceleration) Many detection systems fingerprint canvas and WebGL rendering output and cross-check it against the claimed GPU. Software-rendered browsers produce pixel hashes that don't match any real consumer GPU, which is a strong bot signal on sites with rendering-based fingerprinting. GPU-enabled Kernel browsers render through real hardware, producing output consistent with a normal user's device. -## Getting Started +## Getting started Before you start automating your workflow, we recommend that you manually test your website to understand how it behaves with Kernel's browsers. Here's how to do that: @@ -73,7 +74,7 @@ Before you start automating your workflow, we recommend that you manually test y Once you have a stable baseline, replicate those conditions in your automations. -## Recommended Practices +## Recommended practices | Category | Recommendation | |-----------|----------------| @@ -88,7 +89,7 @@ Once you have a stable baseline, replicate those conditions in your automations. | **Network Identity** | Use stable IP addresses, especially if logging in. See [Choosing a proxy type](#choosing-a-proxy-type) below. | | **Extensions** | Use the [Extensions API](/browsers/extensions) carefully — each adds its own fingerprint, which can be detected. | -## Choosing a Proxy Type +## Choosing a proxy type IP address is one of the strongest signals bot detection systems use. Kernel offers several [proxy types](/proxies/overview), each with different trade-offs for detection avoidance. diff --git a/browsers/bot-detection/stealth.mdx b/browsers/bot-detection/stealth.mdx index 2613bab8..216316da 100644 --- a/browsers/bot-detection/stealth.mdx +++ b/browsers/bot-detection/stealth.mdx @@ -108,20 +108,24 @@ _ = kernelBrowser If you're looking for proxy-level configuration with Kernel browsers, see [Proxies](/proxies/overview). -## CAPTCHA Handling Behavior +## CAPTCHA handling behavior Below are tips for working with Kernel's Stealth Mode auto-CAPTCHA solver across different challenge types and automation frameworks. -### Anthropic Computer Use +### Anthropic computer use Anthropic Computer Use stops when it encounters a CAPTCHA. Use Kernel's auto-CAPTCHA solver by adding this to your prompt: `"If you see a CAPTCHA or similar test, just wait for it to get solved automatically by the browser."` -### Cloudflare Challenge +### Cloudflare challenge When encountering a Cloudflare challenge, our auto-CAPTCHA solver will attempt to handle it. Once the "Ready" message appears on the screen, continue with your intended browser actions (e.g., entering credentials and submitting a login attempt). After the "Ready" message appears, don't click the Cloudflare CAPTCHA checkbox — this can interfere with the solver. + +### hCaptcha (beta) + +KERNEL can also attempt to solve supported hCaptcha challenges automatically. The hCaptcha solver is in beta and isn't enabled for every organization by default. To turn it on, [contact support](/info/support) with the website or workflow you're testing, your expected volume, and whether you already use stealth mode, [profiles](/browsers/profiles), or custom [proxies](/proxies/overview). diff --git a/browsers/computer-controls.mdx b/browsers/computer-controls.mdx index 98471df0..07b6d994 100644 --- a/browsers/computer-controls.mdx +++ b/browsers/computer-controls.mdx @@ -5,6 +5,16 @@ description: "Control the computer's mouse, keyboard, and screen" Use OS-level controls to move and click the mouse, type and press keys, scroll, drag, and capture screenshots from a running browser session. Both `moveMouse` and `dragMouse` use human-like [Bézier curves](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) by default. +## Why computer use for agents + +Kernel's computer controls are built to match how computer-use models were trained — the same primitives the model emits (screenshot, click at coords, type, key, scroll, drag) map 1:1 onto the API. There's no harness translating model output into framework calls. + +- **Native fit.** Screenshot, click, type, key, scroll, drag — the primitives the model already speaks. +- **Faster screenshots.** Captures bypass CDP, which removes the largest source of latency in a vision loop. +- **Better against bot detection.** No CDP connection means no CDP fingerprint to leak. Pairs naturally with [stealth mode](/browsers/bot-detection/stealth) and [residential proxies](/proxies/residential). +- **Human-like input.** OS-level events with Bézier-curve mouse paths, variable typing speed, and configurable mistype rate. +- **Not DOM-limited.** Screenshots capture the full VM, so the agent can see and interact with native dialogs, canvas elements, iframes, and PDFs — not just things you can address with a selector. + ## Click the mouse Simulate mouse clicks at specific coordinates. You can select the button, click type (down, up, click), number of clicks, and optional modifier keys to hold. diff --git a/browsers/concurrency-and-limits.mdx b/browsers/concurrency-and-limits.mdx new file mode 100644 index 00000000..d83c71b0 --- /dev/null +++ b/browsers/concurrency-and-limits.mdx @@ -0,0 +1,68 @@ +--- +title: "Concurrency and Limits" +description: "How many browsers you can run, how fast you can create them, and what each one gets" +--- + +Three separate limits shape a scaled workload, and they're easy to confuse. Concurrency caps how many browsers exist at once. The create rate caps how fast you can ask for new ones. Per-browser resources cap what one browser can do. + +## Concurrency + +One org-wide limit covers every browser you're running, whether created on demand with `browsers.create()` or reserved in a [browser pool](/browsers/pools). The full limit is available to either API in any mix. + +| Limit | Developer | Hobbyist | Start-Up | Enterprise | +| --- | --- | --- | --- | --- | +| Concurrent browsers | 5 | 10 | 150 | Custom | +| App invocations | 5 | 10 | 50 | Custom | +| App invocations (per app) | 5 | 10 | 20 | Custom | +| Managed auth health check interval | 6 hours minimum | 1 hour minimum | 20 minutes minimum | Custom | + +Limits are org-wide unless stated otherwise. + +Two things count against the concurrent browser limit that people don't expect: + +- **Reserved pool capacity counts whether or not it's acquired.** A pool sized to 40 browsers uses 40 of your limit for as long as it exists. +- **Browsers in [standby](/browsers/standby) count.** Standby stops usage charges, not the concurrency slot. Delete the browser to release it. + +Set per-project caps if you're splitting one org limit across teams or environments — see [project concurrency limits](/info/projects#concurrency-limits). + +## Rate limits + +Kernel enforces per-organization rate limits on API requests. Browser creation is rate limited separately from concurrency: the create rate caps how fast you can create browsers, not how many you may run. + +{/* TODO: add the per-plan browser-create rate table once the numbers are confirmed. */} + +Acquiring from a [browser pool](/browsers/pools) isn't subject to the create rate — the pool's browsers already exist. If your traffic arrives in bursts, that's the reason to use a pool even when your concurrency headroom is fine. + +### What happens at the limit + +Exceeding a rate limit returns `429 Too Many Requests`. Rate-limited endpoints include these headers on every response: + +| Header | Description | +| --- | --- | +| `X-RateLimit-Limit` | Maximum requests allowed per minute | +| `X-RateLimit-Remaining` | Requests remaining in the current window | +| `Retry-After` | Seconds to wait before retrying (only on `429` responses) | + +All Kernel SDKs retry a `429` up to 2 times, honoring `Retry-After`. If retries are exhausted, the SDK raises a typed `RateLimitError` carrying the response headers, so you can apply your own backoff. Queue on your side rather than tightening the retry loop: a `429` means the org is over budget for the minute, so retrying faster doesn't help. + +If you're hitting the ceiling in normal operation, [contact us](https://calendly.com/d/d3tn-5kp-5yt) — the limit is raisable. + +## Per-browser resources + +| Resource | Headful | Headless | +| --- | --- | --- | +| Default memory | 8 GB | 1 GB | + +Memory is the practical ceiling on how many tabs and how heavy a page one browser handles. A [headless](/browsers/headless) browser at 1 GB is sized for short-lived, single-page, high-concurrency automation; open a dozen heavy tabs in one and Chromium starts killing renderers. If your workload needs many concurrent pages, spread it across more browsers rather than more tabs in one. Headful browsers support up to 16 GB: set `memory` on a [browser pool](/browsers/pools) when a workload needs more than the default. + +[GPU acceleration](/browsers/gpu-acceleration) is a separate browser type with its own [usage rate](/info/pricing#usage-rates), available on Start-Up and Enterprise. + +## Other limits worth knowing + +| Limit | Where | +| --- | --- | +| Browser `timeout_seconds` (default 60, max 259200 / 72h) | [Termination](/browsers/termination) | +| Pool `timeout_seconds` (default 600) and fill rate | [Browser pools](/browsers/pools) | +| How managed auth health checks run | [Connection lifecycle](/auth/connection-lifecycle) | +| Replay retention, extensions, projects, per plan | [Pricing](/info/pricing#managed-infrastructure) | +| Monthly spend | [Spending caps](/info/spending-caps) | diff --git a/browsers/curl.mdx b/browsers/curl.mdx index e7f372d0..7bc0e680 100644 --- a/browsers/curl.mdx +++ b/browsers/curl.mdx @@ -1,5 +1,6 @@ --- title: "Curl" +sidebarTitle: "Browser Curl" description: "Send HTTP requests through Kernel browsers" --- diff --git a/browsers/live-view.mdx b/browsers/live-view.mdx index 62862928..2682dff7 100644 --- a/browsers/live-view.mdx +++ b/browsers/live-view.mdx @@ -76,7 +76,7 @@ If your environment restricts outbound traffic, allow the [Live View domains and To enable clipboard sharing, add `allow="autoplay; clipboard-read; clipboard-write"` to the iframe element. -If your application uses a **Content Security Policy (CSP)**, you must add the following directives to allow the live view iframe and its WebSocket connection. See [Network access](/info/network-access#content-security-policy) for the complete firewall and CSP requirements. +If your application uses a **Content Security Policy (CSP)**, you must add the following directives to allow the live view iframe and its WebSocket connection. See [firewall allowlist](/info/network-access#content-security-policy) for the complete firewall and CSP requirements. ``` frame-src https://*.onkernel.com:8443 diff --git a/browsers/payments.mdx b/browsers/payments.mdx index eab30059..3003d03b 100644 --- a/browsers/payments.mdx +++ b/browsers/payments.mdx @@ -1,5 +1,6 @@ --- title: "Payments" +sidebarTitle: "Overview" description: "Let browser agents complete purchases without handling raw payment details" --- diff --git a/browsers/performance.mdx b/browsers/performance.mdx index bc6583e0..7b6be4d3 100644 --- a/browsers/performance.mdx +++ b/browsers/performance.mdx @@ -19,7 +19,7 @@ Kernel browsers run in `us-east`. Use our [app platform](/apps/develop) to coloc 2. Create browser rate limit -Kernel enforces [rate limits](/info/pricing#rate-limiting) on browser creation based on your plan. Our SDKs automatically retry, respecting the `Retry-After` header for delay timing. If retries are exhausted, the SDK throws a typed `RateLimitError` with the response headers accessible for custom backoff logic. +Kernel enforces [rate limits](/browsers/concurrency-and-limits#rate-limits) on browser creation based on your plan. Our SDKs automatically retry, respecting the `Retry-After` header for delay timing. If retries are exhausted, the SDK throws a typed `RateLimitError` with the response headers accessible for custom backoff logic. 3. Non-default browser configurations diff --git a/browsers/playwright-execution.mdx b/browsers/playwright-execution.mdx index 92991154..0bb66a33 100644 --- a/browsers/playwright-execution.mdx +++ b/browsers/playwright-execution.mdx @@ -416,14 +416,16 @@ fs.writeFileSync('screenshot.png', buffer); For OS-level screenshots using coordinates and regions, see [Computer Controls](/browsers/computer-controls#take-screenshots). -## Performance benefits + +## Why playwright execution over a direct CDP connection -Compared to connecting over CDP: -- **Lower latency** - Code runs in the same VM as the browser -- **Higher throughput** - No websocket overhead for commands -- **Simpler code** - No need to manage CDP connections +If you're reaching for Playwright, prefer the execution API over `connectOverCDP`. Same Playwright API you already know, none of the setup. -This makes it ideal for one-off operations where you need maximum speed. +- **Run from anywhere.** No `playwright` package to version-pin, no Chromium download, no CDP connection to manage. Send the code, get the result. +- **Co-located with the browser.** Code runs in the same VM as the browser — no network hop between your script and the page, fewer flakes. +- **Patchright by default.** Hardened against bot detection out of the box. +- **Full Playwright API.** `page`, `context`, and `browser` are all in scope. Anything Playwright can do — DOM queries, file uploads, full-page screenshots — works here. +- **Returns values.** `return` from your code and the result comes back in the response. Easy to use as an agent tool. ## MCP server integration diff --git a/browsers/pools.mdx b/browsers/pools.mdx index d83958ee..ceccaf35 100644 --- a/browsers/pools.mdx +++ b/browsers/pools.mdx @@ -5,9 +5,9 @@ description: "Configure a pool of ready-to-use browsers for instant acquisition" A browser pool is a fixed set of identical browsers that Kernel keeps running for you. Configure it once — stealth, proxies, [private networking](/browsers/private-networking), extensions, viewport, a [profile](#profiles-with-browser-pools) — then acquire a browser whenever a task needs one and release it when you're done. -Acquiring is faster than creating an on-demand browser because the browser is already running: you skip start-up, including the [Chromium restart](/browsers/performance#troubleshooting-latency) that some settings trigger, and you aren't subject to the [rate limit](/info/pricing#rate-limiting) on browser creation. +Acquiring is faster than creating an on-demand browser because the browser is already running: you skip start-up, including the [Chromium restart](/browsers/performance#troubleshooting-latency) that some settings trigger, and you aren't subject to the [rate limit](/browsers/concurrency-and-limits#rate-limits) on browser creation. -Idle browsers in a pool aren't billed, but the pool's capacity counts against your [concurrency limit](/info/pricing#concurrency-limits). See [Scale](/introduction/scale) for how browser pools fit into production architecture. +Idle browsers in a pool aren't billed, but the pool's capacity counts against your [concurrency limit](/browsers/concurrency-and-limits#concurrency). See [Scale](/introduction/scale) for how browser pools fit into production architecture. ## How browser pools work @@ -30,7 +30,7 @@ A few constraints to weigh before moving a workload onto a browser pool: - **No GPU browsers.** GPU-accelerated browsers are on-demand only. Use `browsers.create()` for WebGL, video, or canvas-heavy work. - **One fixed configuration per browser pool**, with `start_url` the only setting you can override per acquisition — see [Create a browser pool](#create-a-browser-pool). - **A profile set on the browser pool loads read-only**, and a browser pool holds one at a time — see [Per-user profiles with browser pools](#per-user-profiles-with-browser-pools) for how to persist state per user. -- **Browser pool capacity counts against your [concurrency limit](/info/pricing#concurrency-limits)** whether or not its browsers are acquired, though idle pooled browsers aren't billed. +- **Browser pool capacity counts against your [concurrency limit](/browsers/concurrency-and-limits#concurrency)** whether or not its browsers are acquired, though idle pooled browsers aren't billed. - **Plan-gated.** Browser pools are available on the Start-Up and Enterprise plans. ## Create a browser pool diff --git a/browsers/profiles.mdx b/browsers/profiles.mdx index de1198be..cdc7abae 100644 --- a/browsers/profiles.mdx +++ b/browsers/profiles.mdx @@ -1,5 +1,5 @@ --- -title: "Browser Profiles" +title: "Profiles" sidebarTitle: "Overview" description: "Persist and reuse browser state across browser sessions" --- diff --git a/browsers/regions.mdx b/browsers/regions.mdx index db348d63..726753f3 100644 --- a/browsers/regions.mdx +++ b/browsers/regions.mdx @@ -175,7 +175,7 @@ Browser pool lists support the same filter. Omit it to list resources across all - **Profiles and extensions** aren't tied to a region. You can reuse your existing [profiles](/browsers/profiles) and [extensions](/browsers/extensions) with browsers in any region within the same project. - **Proxy configurations** can be reused across regions. Browser region chooses where the browser runs; [proxy location](/proxies/overview) controls the exit IP websites see. -- **Concurrency and rate limits** apply across all regions combined, not separately in each region. Browser pool capacity counts toward the same [concurrency limit](/info/pricing#concurrency-limits). +- **Concurrency and rate limits** apply across all regions combined, not separately in each region. Browser pool capacity counts toward the same [concurrency limit](/browsers/concurrency-and-limits#concurrency). Regional browsers reduce interaction latency; they don't provide a data residency guarantee. Profiles, replays, and session metadata aren't confined to the browser's selected region and may be stored or processed in the US. diff --git a/browsers/telemetry/categories.mdx b/browsers/telemetry/categories.mdx index fede1c6a..0a20b1cf 100644 --- a/browsers/telemetry/categories.mdx +++ b/browsers/telemetry/categories.mdx @@ -1,5 +1,6 @@ --- title: "Telemetry Categories" +sidebarTitle: "Categories" description: "The categories a browser session can capture, what each contains, and their cost" --- diff --git a/browsers/telemetry/export.mdx b/browsers/telemetry/export.mdx index 6cc11018..39c11bf2 100644 --- a/browsers/telemetry/export.mdx +++ b/browsers/telemetry/export.mdx @@ -1,5 +1,6 @@ --- title: "Export Telemetry" +sidebarTitle: "Export" description: "Send a session's captured events to your own observability backend over OTLP" --- diff --git a/browsers/telemetry/overview.mdx b/browsers/telemetry/overview.mdx index f98f5b3c..f129baf8 100644 --- a/browsers/telemetry/overview.mdx +++ b/browsers/telemetry/overview.mdx @@ -1,5 +1,6 @@ --- -title: "Telemetry Overview" +title: "Browser Telemetry" +sidebarTitle: "Overview" description: "Capture what happens inside a browser session" --- diff --git a/browsers/telemetry/streaming.mdx b/browsers/telemetry/streaming.mdx index 5f064ade..f096f856 100644 --- a/browsers/telemetry/streaming.mdx +++ b/browsers/telemetry/streaming.mdx @@ -1,5 +1,6 @@ --- title: "Stream Telemetry" +sidebarTitle: "Streaming" description: "Consume a session's live telemetry stream from the SDK or CLI" --- diff --git a/changelog.mdx b/changelog.mdx index 57a2837e..0fd233cf 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -168,7 +168,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n ## Documentation updates -- Added a [Foreman integration guide](/integrations/vercel/foreman) to the Vercel section. +- Added a [Foreman integration guide](/cookbooks/eve-foreman) to the Vercel section. - Documented [replay iframe embedding](/browsers/replays) for embedding session replays inside your own dashboards. - Documented the 30-day retention window for browser telemetry events. - Documented automatic [proxy](/proxies/overview) cleanup behavior. @@ -396,7 +396,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n ## Documentation updates -- Added a new [hCaptcha](/browsers/bot-detection/hcaptcha) page documenting beta support for hCaptcha solving. +- Added a new [hCaptcha](/browsers/bot-detection/stealth#hcaptcha-beta) page documenting beta support for hCaptcha solving. - Refreshed [managed auth](/auth/managed-auth) documentation for May 2026: new dedicated [connection lifecycle](/auth/connection-lifecycle) page covering health checks and re-authentication, a shared [connection configuration](/auth/configuration) reference, documented `success_url` / `error_url` query parameters for the [hosted UI](/auth/hosted-ui), [`start_url`](/browsers/create-a-browser) references across browser and pool docs, a reorganized sidebar, and new FAQ entries for short-session reauth and multi-step login forms. - Clarified that managed residential proxy IPs are stable within a session but are not guaranteed to persist across sessions. - Updated the [Yutori integration guide](/integrations/computer-use/yutori) to Navigator n1.5. @@ -446,7 +446,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n - Anti-detection features are now on by default for all Kernel browsers. [Stealth mode](/browsers/bot-detection/stealth) now specifically adds the managed ISP proxy and CAPTCHA solver (both opt-out), and non-stealth browsers fully support [custom proxies](/proxies/custom). - Revamped the [managed auth hosted login page](/auth/hosted-ui): all available sign-in options (password fields, SSO providers, MFA, alternate sign-in methods) now render together on a single page, so end users can pick the path they want, instead of being funneled through one at a time. - Managed auth input fields now display contextual helper text when the site surfaces hints, reducing user confusion on multi-step logins. -- The "Save credentials after login" option is now automatically disabled when [1Password](/integrations/1password) is selected as the [credential source](/auth/credentials), since those credentials are already managed externally. +- The "Save credentials after login" option is now automatically disabled when [1Password](/integrations/1password) is selected as the [credential source](/auth/configuration#credentials-and-auto-reauth), since those credentials are already managed externally. - Kernel now supports WebSocket connections through its API, enabling `process attach` and other long-lived streaming workflows. - Exceeding invocation concurrency limits now returns a 429 response immediately, for faster and more actionable feedback. @@ -501,7 +501,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n ## Documentation updates -- Added [API rate limiting](/info/pricing#rate-limiting) documentation. +- Added [API rate limiting](/browsers/concurrency-and-limits#rate-limits) documentation. - Documented the [`disable_default_proxy`](/browsers/bot-detection/stealth) option for stealth browsers. - Updated [live view embedding](/browsers/live-view) docs with iframe focus tips, clipboard sharing guidance, and CSP configuration. - Documented [managed auth re-authentication triggers](/auth/managed-auth). @@ -610,7 +610,7 @@ For API library updates, see the [Node SDK](https://github.com/onkernel/kernel-n - Fixed screen resize accuracy by removing unnecessary rounding in `ChangeScreenSize` to ensure pixel-perfect display dimensions. ## Documentation updates -- Enhanced [secrets](/apps/secrets) documentation with practical examples for LLM-powered applications and detailed guidance for deploying apps with environment file configurations. +- Enhanced [secrets](/apps/deploy#secrets) documentation with practical examples for LLM-powered applications and detailed guidance for deploying apps with environment file configurations. diff --git a/cookbooks.mdx b/cookbooks.mdx index bbdea841..d21a0b8d 100644 --- a/cookbooks.mdx +++ b/cookbooks.mdx @@ -1,5 +1,6 @@ --- title: "cookbooks" +sidebarTitle: "Cookbooks" description: "end-to-end recipes to teach agents to use the internet" mode: "wide" --- @@ -13,22 +14,22 @@ import { CookbookSearch } from '/snippets/cookbook-search.jsx'; ## Common patterns - -
common patterns
- Collect credentials from a human, then let your agent fill the form. - - -
common patterns
- Enable Payments in a Browser Agent. -
common patterns
Using Playwright with computer use fallback. + +
common patterns
+ Collect credentials from a human, then let your agent fill the form. +
common patterns
Use WebMCP for supported page actions and Browser REPL helpers for everything else. + +
common patterns
+ Enable Payments in a Browser Agent. +
common patterns
Hold an agent while Kernel's captcha solver works, and tell it what actually happened. @@ -37,77 +38,94 @@ import { CookbookSearch } from '/snippets/cookbook-search.jsx'; ## Harnesses & models +### Computer use models + - +
harnesses & models
- Run a browser use loop with Jev System One. + Minimal implementation of Anthropic's computer use loop. - +
harnesses & models
- Browser automation with the Vercel AI SDK and KERNEL's Playwright execution API. + Computer use agent with Google's Gemini 2.5 and Stagehand. + + +
harnesses & models
+ Run the Browser Use bu-1.0 model on KERNEL browser infrastructure. + + +
harnesses & models
+ Run a browser use loop with Jev System One.
harnesses & models
RL training for computer use agents, using Tinker. - + + +### Agent and automation frameworks + + +
harnesses & models
- Human-in-the-loop web task assistant with memory, built on Mastra. + Browser automation with the Vercel AI SDK and KERNEL's Playwright execution API. - +
harnesses & models
- Host a Jev browser use agent on Val Town. + Human-in-the-loop web task assistant with memory, built on Mastra. - +
harnesses & models
- Run parallel computer-use agent swarms, with API keys secured via Vaults. + Run agentic and deterministic end-to-end checks in a KERNEL browser with e2e. - +
harnesses & models
- QA your PR previews with Claude computer use on Modal, recorded with Replays. + Vibium browser automation over WebDriver BiDi. - + + +### Hosted agents + + +
harnesses & models
- Run the Browser Use bu-1.0 model on KERNEL browser infrastructure. + Run parallel computer-use agent swarms, with API keys secured via Vaults.
harnesses & models
Build a browser agent with eve and KERNEL managed auth. - +
harnesses & models
- Computer use agent with Google's Gemini 2.5 and Stagehand. + Build a Link and Eve agent that browses with KERNEL and uses a Link wallet for approved purchases. - +
harnesses & models
- Minimal implementation of Anthropic's computer use loop. + Give Vercel foreman access to a KERNEL browser for QA. - +
harnesses & models
- Vibium browser automation over WebDriver BiDi. + Run Vercel's fx agent inside a KERNEL browser VM, co-located with the browser it drives. - + + +### Sandboxes and platforms + + +
harnesses & models
- Scrape JS-rendered pages behind a login, on Modal with a KERNEL browser. + QA your PR previews with Claude computer use on Modal, recorded with Replays. - +
harnesses & models
- Give Vercel foreman access to a KERNEL browser for QA. + Scrape JS-rendered pages behind a login, on Modal with a KERNEL browser.
harnesses & models
Connect e2b sandboxes with KERNEL browsers. - -
harnesses & models
- Run Vercel's fx agent inside a KERNEL browser VM, co-located with the browser it drives. - - -
harnesses & models
- Run agentic and deterministic end-to-end checks in a KERNEL browser with e2e. - - +
harnesses & models
- Build a Link and Eve agent that browses with KERNEL and uses a Link wallet for approved purchases. + Host a Jev browser use agent on Val Town. diff --git a/docs.json b/docs.json index 4fee7e73..13374344 100644 --- a/docs.json +++ b/docs.json @@ -6,6 +6,11 @@ { "source": "/careers/backend-engineer", "destination": "https://jobs.ashbyhq.com/usekernel" }, { "source": "/careers/engineer-new-grad", "destination": "https://jobs.ashbyhq.com/usekernel" }, { "source": "/careers/customer-engineer", "destination": "https://jobs.ashbyhq.com/usekernel" }, + { "source": "/browsers/bot-detection/hcaptcha", "destination": "/browsers/bot-detection/stealth#hcaptcha-beta" }, + { "source": "/overview/products", "destination": "/overview/features" }, + { "source": "/apps/secrets", "destination": "/apps/deploy#secrets" }, + { "source": "/integrations/vercel/foreman", "destination": "/cookbooks/eve-foreman" }, + { "source": "/apps/stop", "destination": "/apps/invoke#stop-an-invocation" }, { "source": "/auth/agent/overview", "destination": "/auth/managed-auth" }, { "source": "/auth/agent/hosted-ui", "destination": "/auth/hosted-ui" }, { "source": "/auth/agent/programmatic", "destination": "/auth/programmatic" }, @@ -19,8 +24,9 @@ { "source": "/profiles.md", "destination": "/browsers/profiles.md" }, { "source": "/profiles/overview", "destination": "/browsers/profiles" }, { "source": "/profiles/overview.md", "destination": "/browsers/profiles.md" }, - { "source": "/profiles/credentials", "destination": "/auth/credentials" }, - { "source": "/profiles/credentials.md", "destination": "/auth/credentials.md" }, + { "source": "/profiles/credentials", "destination": "/auth/configuration#credentials-and-auto-reauth" }, + { "source": "/profiles/credentials.md", "destination": "/auth/configuration.md" }, + { "source": "/auth/credentials", "destination": "/auth/configuration#credentials-and-auto-reauth" }, { "source": "/profiles/managed-auth", "destination": "/auth/managed-auth" }, { "source": "/profiles/managed-auth.md", "destination": "/auth/managed-auth.md" }, { "source": "/profiles/managed-auth/overview", "destination": "/auth/managed-auth" }, @@ -42,7 +48,7 @@ { "source": "/browsers/pools/overview", "destination": "/browsers/pools" }, { "source": "/browsers/pools/faq", "destination": "/browsers/pools" }, { "source": "/introduction", "destination": "/" }, - { "source": "/quickstart", "destination": "/" }, + { "source": "/quickstart", "destination": "/start/quickstart" }, { "source": "/home", "destination": "/" }, { "source": "/llm.md", "destination": "/integrations/stripe-projects" }, { "source": "/llm-browser.md", "destination": "/integrations/stripe-projects-browser" }, @@ -103,6 +109,9 @@ } ] }, + "seo": { + "indexing": "all" + }, "navigation": { "tabs": [ { @@ -112,24 +121,47 @@ "group": "Overview", "pages": [ "index", - "introduction/create", - "introduction/control", - "introduction/observe", - "introduction/scale" + "overview/features", + "overview/concepts", + "overview/why-kernel" + ] + }, + { + "group": "Start building", + "pages": [ + "start/quickstart", + "skills/overview", + "integrations/overview", + "cookbooks" ] }, { - "group": "Working with your browser", + "group": "How it works", "pages": [ { - "group": "Basics", - "expanded": true, + "group": "Configure", "pages": [ - "browsers/live-view", - "browsers/termination", - "browsers/standby", - "browsers/headless", - "info/projects", + "introduction/configure", + { + "group": "Stealth", + "pages": [ + "browsers/bot-detection/overview", + "browsers/bot-detection/stealth", + "browsers/bot-detection/web-bot-auth" + ] + }, + { + "group": "Proxies", + "pages": [ + "proxies/overview", + "proxies/residential", + "proxies/isp", + "proxies/mobile", + "proxies/datacenter", + "proxies/custom", + "proxies/errors" + ] + }, { "group": "Profiles", "pages": [ @@ -138,46 +170,23 @@ "browsers/profiles/concurrency", "browsers/profiles/agent-patterns" ] - } - ] - }, - { - "group": "Intermediate", - "expanded": true, - "pages": [ + }, { - "group": "Bot Anti-Detection", + "group": "Vaults", "pages": [ - "browsers/bot-detection/overview", - "browsers/bot-detection/stealth", - "browsers/bot-detection/hcaptcha", - { - "group": "Proxies", - "pages": [ - "proxies/overview", - "proxies/custom", - "proxies/residential", - "proxies/mobile", - "proxies/isp", - "proxies/datacenter", - "proxies/errors" - ] - }, - "browsers/bot-detection/web-bot-auth", - "bots" + "vaults/overview", + "vaults/credentials", + "vaults/existing-credential-vault", + "vaults/fill", + "vaults/1password" ] }, { - "group": "Auth", + "group": "Authentication", "pages": [ "auth/overview", - { - "group": "Fill from Vault", - "pages": [ - "auth/fill-from-vault", - "auth/fill-from-managed-auth" - ] - }, + "auth/fill-from-vault", + "auth/fill-from-managed-auth", { "group": "Managed Auth", "pages": [ @@ -186,180 +195,120 @@ "auth/react", "auth/programmatic", "auth/configuration", - "auth/connection-lifecycle", - "auth/credentials", - "auth/faq" + "auth/connection-lifecycle" ] } ] }, { - "group": "Vaults", + "group": "Payments", "pages": [ - "vaults/overview", - "vaults/credentials", - "vaults/existing-credential-vault", - "vaults/fill", - "vaults/1password" + "browsers/payments", + "integrations/wallets/overview", + "integrations/wallets/stripe-link", + "integrations/wallets/agentcard" ] }, - "browsers/payments", - "browsers/replays", - "browsers/viewport", - "browsers/regions", - "browsers/gpu-acceleration", - "config-registry", - "info/api-keys", - "info/audit-logs", - "browsers/file-io", - "browsers/process-execution", - "browsers/curl", - "browsers/ssh", - "browsers/computer-controls", + "config-registry" + ] + }, + { + "group": "Control", + "pages": [ + "introduction/control", "browsers/playwright-execution", + "browsers/computer-controls", "browsers/webmcp", - "browsers/repl" + "browsers/repl", + "browsers/process-execution", + "browsers/file-io", + { + "group": "Code Execution Platform", + "pages": [ + "apps/develop", + "apps/deploy", + "apps/invoke", + "apps/status", + "apps/logs" + ] + } ] }, { - "group": "Advanced", - "expanded": true, + "group": "Scale", "pages": [ - "browsers/extensions", - "browsers/private-networking", - "browsers/chrome-policies", + "introduction/scale", + "browsers/concurrency-and-limits", + "browsers/performance", + "browsers/pools" + ] + }, + { + "group": "Observe", + "pages": [ + "introduction/observe", + "browsers/live-view", + "browsers/replays", { - "group": "Telemetry", + "group": "Browser Telemetry", "pages": [ "browsers/telemetry/overview", "browsers/telemetry/categories", "browsers/telemetry/streaming", "browsers/telemetry/export" ] - }, - "browsers/pools" + } ] }, { - "group": "FAQ", + "group": "Manage", "pages": [ - "browsers/performance" + "introduction/manage", + "info/projects", + "info/api-keys", + "info/audit-logs", + "info/network-access" ] } ] }, { - "group": "Integrations", + "group": "Partnering with KERNEL", "pages": [ - "integrations/overview", - "integrations/browser-use", { - "group": "Claude", - "icon": "/images/integration-icons/claude.svg", + "group": "Plans and Billing", "pages": [ - "integrations/claude/overview", - "integrations/claude/claude-code-and-desktop", - "integrations/claude/claude-agent-sdk", - "integrations/claude/claude-managed-agents" + "info/pricing", + "info/spending-caps", + "info/mpp" ] }, { - "group": "Computer Use Models", - "icon": "/images/integration-icons/computer-cursor-rounded.svg", + "group": "Security and Trust", "pages": [ - "integrations/computer-use/overview", - "integrations/computer-use/anthropic", - "integrations/computer-use/gemini", - "integrations/computer-use/openagi", - "integrations/computer-use/openai", - "integrations/computer-use/tzafon", - "integrations/computer-use/yutori" + "shared-responsibility-model", + "info/trust-center", + "security-vulnerability-reporting", + "bots" ] }, { - "group": "Wallets", - "icon": "/images/integration-icons/payments.svg", + "group": "Enterprise", "pages": [ - "integrations/wallets/overview", - "integrations/wallets/stripe-link", - "integrations/wallets/agentcard" + "info/enterprise", + "info/hipaa", + "info/zero-data-retention", + "info/contact-sales" ] }, - "integrations/docker-sandboxes", - "integrations/e2e", - "integrations/hermes-agent", - "integrations/laminar", - "integrations/replit", - "integrations/stagehand", { - "group": "Stripe Projects", - "icon": "/images/integration-icons/stripe.svg", + "group": "Support and Community", "pages": [ - "integrations/stripe-projects", - "integrations/stripe-projects-browser" + "info/support", + "community/discord", + "community/github" ] - }, - "integrations/terraform", - "integrations/valtown", - { - "group": "Vercel", - "icon": "/images/integration-icons/vercel.svg", - "pages": [ - "integrations/vercel/overview", - "integrations/vercel/agent-browser", - "integrations/vercel/ai-sdk", - "integrations/vercel/marketplace", - "integrations/vercel/eve-extension", - "integrations/vercel/foreman", - "integrations/vercel/fx" - ] - }, - "integrations/vibium", - "integrations/1password" - ] - }, - { - "group": "deploying your agent", - "pages": [ - "apps/develop", - "apps/deploy", - "apps/invoke", - "apps/stop", - "apps/secrets", - "apps/status", - "apps/logs" - ] - }, - { - "group": "Agent Skills", - "pages": [ - "skills/overview", - "skills/kernel-cli", - "skills/bot-detection", - "skills/profiles", - "skills/kernel-auth", - "skills/create-site-skills" - ] - }, - { - "group": "Community", - "pages": [ - "community/github", - "community/discord" - ] - }, - { - "group": "Info", - "pages": [ - "info/network-access", - "browsers/faq", - "info/concepts", - "info/zero-data-retention", - "info/pricing", - "info/spending-caps", - "info/support", - "info/unikernels", - "info/mpp" + } ] } ] @@ -368,45 +317,6 @@ "tab": "API Reference", "openapi": "https://api.onkernel.com/spec.json" }, - { - "tab": "Cookbooks", - "pages": [ - "cookbooks", - { - "group": "Common Patterns", - "pages": [ - "browsers/playwright-computer-use-fallback", - "browsers/code-mode-webmcp", - "browsers/telemetry/pausing-for-captcha-solves", - "browsers/enable-payments-in-browser-agent", - "browsers/use-vault-credentials-in-browser-agent" - ] - }, - { - "group": "Harnesses & Models", - "pages": [ - "cookbooks/ai-sdk-agent", - "cookbooks/browser-use-model", - "cookbooks/claude-managed-agents", - "cookbooks/claude-computer-use-loop", - "cookbooks/e2b", - "cookbooks/e2e-kernel", - "cookbooks/eve-foreman", - "cookbooks/eve-managed-auth", - "cookbooks/fx-colocated-agent", - "cookbooks/jev-browser-use", - "cookbooks/jev-browser-use-val-town", - "cookbooks/mastra-web-task-assistant", - "cookbooks/modal-web-scraper", - "cookbooks/modal-pr-qa-agent", - "cookbooks/personal-shopper", - "cookbooks/stagehand-google-cua-agent", - "cookbooks/tinker-rl", - "cookbooks/vibium" - ] - } - ] - }, { "tab": "CLI", "groups": [ diff --git a/eyebrow.js b/eyebrow.js new file mode 100644 index 00000000..30a839d7 --- /dev/null +++ b/eyebrow.js @@ -0,0 +1,42 @@ +/* + * Hide the page eyebrow when it repeats the page title. + * + * Mintlify shows the sidebar group name above every page title. On a section's + * overview page the title is the section name, so the eyebrow would repeat it. + * Mintlify loads every .js file in this directory on every docs page and + * navigates client-side, so re-check whenever the header changes. + */ +(function () { + function sync() { + var header = document.getElementById("header"); + if (!header) return; + var eyebrow = header.querySelector(".eyebrow"); + var title = document.getElementById("page-title"); + if (!eyebrow || !title) return; + var same = + eyebrow.textContent.trim().toLowerCase() === + title.textContent.trim().toLowerCase(); + eyebrow.style.display = same ? "none" : ""; + } + + var scheduled = false; + function schedule() { + if (scheduled) return; + scheduled = true; + requestAnimationFrame(function () { + scheduled = false; + sync(); + }); + } + + if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", sync); + } else { + sync(); + } + new MutationObserver(schedule).observe(document.documentElement, { + childList: true, + subtree: true, + characterData: true, + }); +})(); diff --git a/images/integration-icons/openagi.svg b/images/integration-icons/openagi.svg new file mode 100644 index 00000000..ab1d37e7 --- /dev/null +++ b/images/integration-icons/openagi.svg @@ -0,0 +1,4 @@ + + + + diff --git a/images/integration-icons/openai.svg b/images/integration-icons/openai.svg new file mode 100644 index 00000000..887c1f49 --- /dev/null +++ b/images/integration-icons/openai.svg @@ -0,0 +1 @@ +OpenAI \ No newline at end of file diff --git a/images/integration-icons/tzafon.svg b/images/integration-icons/tzafon.svg new file mode 100644 index 00000000..7a93f6b7 --- /dev/null +++ b/images/integration-icons/tzafon.svg @@ -0,0 +1,3 @@ + + + diff --git a/images/integration-icons/yutori.png b/images/integration-icons/yutori.png new file mode 100644 index 00000000..1b5e30e5 Binary files /dev/null and b/images/integration-icons/yutori.png differ diff --git a/images/overview/agent-stack.svg b/images/overview/agent-stack.svg new file mode 100644 index 00000000..7b678d73 --- /dev/null +++ b/images/overview/agent-stack.svg @@ -0,0 +1,49 @@ + + + + +agent framework +runs the loop: ask the model, act, repeat + +model + +system prompt + +tools + +skills + +browser automation framework + +KERNEL +browser infrastructure + +chromium vm + +stealth + +proxies + +profiles + +auth + +payments + +the internet +real websites + + + + + + + + + + +drives + +https +your agent drives KERNEL browsers with playwright, computer controls, cdp, webdriver bidi, or mcp tools. + diff --git a/images/overview/cookbooks.svg b/images/overview/cookbooks.svg new file mode 100644 index 00000000..6cf6d1b9 --- /dev/null +++ b/images/overview/cookbooks.svg @@ -0,0 +1,17 @@ + + + +cookbooks + + +playwright + computer use + +human-in-the-loop credentials + +agentic payments + + + + +github.com/kernel/cookbooks + diff --git a/images/overview/quickstart.svg b/images/overview/quickstart.svg new file mode 100644 index 00000000..8b327157 --- /dev/null +++ b/images/overview/quickstart.svg @@ -0,0 +1,15 @@ + + + +give your agent the internet + +copy prompt + + + + +$ kernel login +$ npx skills add kernel/skills +$ kernel browsers create + + diff --git a/index.mdx b/index.mdx index 801dbaa8..e8e8eb33 100644 --- a/index.mdx +++ b/index.mdx @@ -5,74 +5,47 @@ description: "" mode: "wide" --- -We build crazy fast, open source infra for AI agents to access the internet. Trusted by Cash App, Framer, and 11,000 teams. +KERNEL is the internet runtime for agents. we provide crazy fast, open source browser infra for your agents to access and act on the internet. each chromium browser is pre-configured with anti-detection defaults, runs in its own vm with isolated resources, and can be driven with browser automation frameworks, computer controls, or cdp and webdriver bidi directly. beyond browsers, KERNEL provides a platform of infrastructure primitives so your agents have what they need on real websites: stealth and proxies, authentication, payments, live view, replays, and more. - - - We spin up cloud browsers in <30ms with GPU acceleration when needed. - - - choose Managed Auth or Fill from Vault for browser agents. +## why we built it this way + +most browser infrastructure runs chromium in containers orchestrated by kubernetes, with warm pools to hide slow starts. we [pioneered](https://www.kernel.sh/blog/scale) a different approach: running chromium on unikernels, single-purpose vms that carry only what the browser needs. + +a unikernel carries the browser and nothing else, so there's little to boot or keep running. running every browser this way has many benefits, including: + +- **lifecycle actions are fast.** a browser is created in about 30ms at p50 and 105ms at p99 ([benchmarks](https://www.kernel.sh/benchmarks)), so you can create one per task instead of keeping a warm pool alive to hide start-up time. +- **code on the vm is safe to hand an agent.** every browser is its own vm, isolated at the hypervisor rather than sharing a host kernel with other tenants, so the [browser repl](/browsers/repl), [process execution](/browsers/process-execution), and root access over [ssh](/browsers/ssh) stay contained to that session. +- **idle browsers go into standby.** five seconds after the last client disconnects, a browser enters [standby](/browsers/standby): it keeps its state and stops accruing usage cost until a client reconnects. + +## open source + +we value open source and transparency, so we publish the browser image and the vm runtime behind KERNEL browsers on github. you can read exactly what runs your agent's browser, run it yourself, or contribute. + + + + the chromium images behind KERNEL browsers. - - We solve CAPTCHAs and manage residential proxies to help you see fewer of them. + + the vm runtime we built to run browsers. - - You can view sessions live and record them as MP4s for debugging. + + our fork of the cloud hypervisor virtual machine monitor. -## start here + + + +## get started - - - Spin up a browser and pick the shape — headless, stealth, GPU, profiles. + + + browsers, stealth, proxies, auth, payments, and everything else, each linking to its docs. - - Drive it with computer use, playwright execution, CDP, or WebDriver BiDi. + + hand setup to your coding agent with one prompt, or create your first browser yourself. - - Watch it live, record replays, and capture screenshots. + + end-to-end recipes you can clone and run, from computer use fallbacks to agentic payments. - -import { CopyPromptButton } from '/snippets/copy-prompt-button.jsx'; - -
-

fast setup

-
-
- - -
-
-

- copy and paste this into your AI coding agent (Cursor, Claude, Windsurf, etc.). it installs the Kernel CLI and skills, authenticates you, and opens a live browser session that you or your agent can interact with. -

-
- -
-
-
-
- -## prod setup - -Our [app platform](/apps/develop) is a serverless compute service for running agent loops triggered on demand or by scheduled events without having to provision or manage sandboxes. Your agent runs co-located with its browser to minimize network latency. - -Scaffold a project from a template: - -```bash -kernel create --template computer-use -``` - -Deploy and invoke it on demand: - -```bash -kernel deploy agent.ts -kernel invoke my-agent my-task --payload '{"url": "https://example.com"}' -``` - -### scaling - -[browser pools](/browsers/pools) keep browsers ready to use and pre-configured, so you skip start-up latency on every task and idle browsers aren't billed. reach for them once you're running the same workload repeatedly, need low-latency acquisition, or are scaling steady, high-frequency traffic — on-demand `browsers.create()` stays the right call for occasional, bursty, or one-off work. diff --git a/info/contact-sales.mdx b/info/contact-sales.mdx new file mode 100644 index 00000000..1e2f1269 --- /dev/null +++ b/info/contact-sales.mdx @@ -0,0 +1,18 @@ +--- +title: "Contact Sales" +description: "Talk to Kernel about an enterprise plan, custom limits, or a pilot" +--- + +**[Book a call](https://calendly.com/d/d3tn-5kp-5yt).** + +Worth reaching out when: + +- You need **custom concurrency or create-rate limits** beyond the published plans — see [concurrency and limits](/browsers/concurrency-and-limits). +- You need a **BAA, zero data retention, or continuous audit log export** — see [Enterprise](/info/enterprise). +- You're **migrating a fleet** and want help choosing between browser pools, on-demand browsers, and the [code execution platform](/apps/develop). +- You're running **thousands of end-user identities** and want the project and profile layout reviewed. +- Your target sites have **aggressive bot detection** and you want them tested before you commit. + +Bring the sites you need to automate, your expected concurrency, and how the automation is triggered. That's usually enough to scope pricing and the right architecture on the first call. + +Already a customer with a support question? Use [support](/info/support) instead. diff --git a/info/enterprise.mdx b/info/enterprise.mdx new file mode 100644 index 00000000..55df691b --- /dev/null +++ b/info/enterprise.mdx @@ -0,0 +1,39 @@ +--- +title: "Enterprise" +sidebarTitle: "Overview" +description: "HIPAA, zero data retention, custom limits, and support on KERNEL's Enterprise plan" +--- + +What changes on the Enterprise plan. + +## HIPAA + +KERNEL signs a BAA on the Enterprise plan. See [HIPAA](/info/hipaa) for what KERNEL provides and what you're responsible for. + +## Zero data retention + +[Zero data retention](/info/zero-data-retention) is Enterprise-only and configured per organization. With it enabled, session recordings, live view streams, and telemetry aren't retained after the browser terminates. + +## What else the Enterprise plan includes + +| | Enterprise | +| --- | --- | +| Concurrency and rate limits | Custom limits for concurrency and browser creation. See [concurrency and limits](/browsers/concurrency-and-limits). | +| Audit logs | [Continuous export to S3](/info/audit-logs#continuous-s3-export), in addition to search and download | +| Replay retention | Custom [replay](/browsers/replays) retention | +| [Support](/info/support) | A shared Slack channel, with tiered response times | +| Data processing | [DPA](/dpa) | + +The full plan comparison is on [pricing](/info/pricing). For KERNEL's security program, compliance reports, and the shared responsibility model, see [security practices](/security) and the [trust center](/info/trust-center). + +## Legal + +- [Terms of service](/tos) +- [Privacy policy](/privacy) +- [Acceptable use policy](/acceptable-use) +- [Data processing addendum](/dpa) +- [Vulnerability reporting](/security-vulnerability-reporting) + +## Talk to us + +Scoping an enterprise deployment, a BAA, or zero data retention starts with a conversation: [contact sales](/info/contact-sales). diff --git a/info/hipaa.mdx b/info/hipaa.mdx new file mode 100644 index 00000000..0656bf21 --- /dev/null +++ b/info/hipaa.mdx @@ -0,0 +1,16 @@ +--- +title: "HIPAA" +description: "Run browser workflows that handle protected health information on KERNEL's Enterprise plan" +--- + +KERNEL supports HIPAA compliance for workflows that handle protected health information (PHI), and signs a business associate agreement (BAA) on the Enterprise plan. + +## What KERNEL provides + +- **A BAA.** KERNEL signs a BAA with Enterprise customers. [Contact sales](/info/contact-sales) to start one. +- **Isolation per browser.** Each browser runs in its own VM with its own kernel and filesystem, isolated from other sessions at the hypervisor. +- **Zero data retention.** With [zero data retention](/info/zero-data-retention), session recordings, live view streams, and telemetry aren't retained after a browser terminates. Turn it on if PHI must not persist after a session ends. + +## What you're responsible for + +HIPAA compliance is shared. KERNEL secures the platform; you're responsible for how your agents use it, such as which sites they access, what data they extract, and where that data goes. See the [shared responsibility model](/shared-responsibility-model) for the full split, and [security practices](/security) for KERNEL's program and current compliance status. diff --git a/info/network-access.mdx b/info/network-access.mdx index 64fe89cf..44ea7259 100644 --- a/info/network-access.mdx +++ b/info/network-access.mdx @@ -1,5 +1,6 @@ --- -title: "Network Access" +title: "Allowlist KERNEL Domains" +sidebarTitle: "Firewall Allowlist" description: "Domain and port allowlist for connecting to Kernel" --- diff --git a/info/pricing.mdx b/info/pricing.mdx index 69b7e5c1..fe834374 100644 --- a/info/pricing.mdx +++ b/info/pricing.mdx @@ -1,8 +1,9 @@ --- -title: "Pricing & Limits" +title: "Pricing" +sidebarTitle: "Plans and Pricing" --- -With Kernel, you only pay for what you use and nothing more. You don't pay for idle time thanks to [Standby Mode](/browsers/standby), idle browsers in a browser pool incur no usage charges, and you're never charged for proxies. +With Kernel, you only pay for what you use and nothing more. You don't pay for idle time thanks to [Standby Mode](/browsers/standby), and idle browsers in a browser pool incur no usage charges. ## Plan Pricing | Plan | Monthly cost | Included Credits / mo @@ -55,69 +56,47 @@ import { PricingCalculator } from '/snippets/calculator.jsx'; | HIPAA compliance (BAA) | ❌ | ❌ | ❌ | ✅ | -## Concurrency limits + + + +## Limits -Kernel enforces a single concurrency limit covering all browsers you run at once—whether created on demand with `browsers.create()` or reserved in a [browser pool](/browsers/pools/overview). Your full limit is available to either API in any mix. +Concurrency, rate limits, and per-browser resources for each plan are on [concurrency and limits](/browsers/concurrency-and-limits). -| Feature | Developer | Hobbyist | Start-Up | Enterprise | -| --- | --- | --- | --- | --- | -| Concurrent browsers | 5 | 10 | 150 | Custom | -| App invocations | 5 | 10 | 50 | Custom | -| App invocations (per-app) | 5 | 10 | 20 | Custom | -| Managed auth health check interval | 6 hours minimum | 1 hour minimum | 20 minutes minimum | Custom | - -#### Notes -- Reserved capacity in a [browser pool](/browsers/pools/overview) counts toward your concurrency limit whether or not the browsers are currently acquired—a pool sized to 40 browsers uses 40 of your limit. -- Browsers in [Standby Mode](/browsers/standby) count against your concurrency limit. -- Limits are org-wide by default unless stated otherwise. - - -## Rate limiting - -Kernel enforces per-organization rate limits on API requests. When you exceed the rate limit, the API returns a `429 Too Many Requests` response with a `Retry-After` header indicating how many seconds to wait before retrying. - -Rate-limited endpoints include these headers on every response: - -| Header | Description | -| --- | --- | -| `X-RateLimit-Limit` | Maximum requests allowed per minute | -| `X-RateLimit-Remaining` | Requests remaining in the current window | -| `Retry-After` | Seconds to wait before retrying (only on `429` responses) | - -All Kernel SDKs automatically retry `429` responses up to 2 times, respecting the `Retry-After` header for delay timing. If retries are exhausted, the SDK throws a typed `RateLimitError` with the response headers accessible for custom backoff logic. +## Other ways to pay -If you need higher rate limits, [contact us](https://calendly.com/d/d3tn-5kp-5yt). +Agents can buy a single browser without a KERNEL account or API key through the [machine payments protocol (MPP)](/info/mpp). One stealth, headful browser for 30 minutes costs \$0.50, paid with a Link payment. See [buy a browser with MPP](/info/mpp) for the payment flow. ## FAQ - -App invocations are billed for active compute time, not per API call. The invocation rate in [Usage Rates](#usage-rates) is based on the current 4 GB memory allocation at $0.0000166667 per GB-second. - -Billing starts when your code begins executing and stops when it finishes. You aren't charged for queued time, deploying an app, or leaving a deployed app idle. Failed and canceled invocations still accrue charges for the time they ran. - -Browsers created by an invocation are billed separately for their active runtime at the browser rates above. Services your code calls, such as an LLM API, also bill you independently. - -The [app invocation limits](#concurrency-limits) are concurrency limits, not a number of invocations included with your plan. - - - see this guide on [spending controls](/info/spending-caps). - Only for active runtime. `timeout_seconds` sets an idle auto-delete ceiling, not a billing window. Once a browser goes idle — 5 seconds after the last CDP or Live View activity — it enters Standby Mode and stops accruing usage cost, even if it stays alive until the timeout is reached. Deleting a browser early doesn't lower cost any further (idle time is already free), but it does free up your concurrency slot sooner. + + Set an organization or project [spending cap](/info/spending-caps). + you pay the standard usage-based price per GB-second while browsers are running. Idle browsers in a pool incur no disk charges—you only pay when a browser is actively in use. - Note: A browser pool counts toward your concurrency limit whether or not its browsers are currently acquired — a browser pool sized to 40 browsers uses 40 of your limit. Browser pools are available on Start-Up and Enterprise plans. + Note: A browser pool counts toward your concurrency limit whether or not its browsers are currently acquired — a browser pool sized to 40 browsers uses 40 of your limit. Managed Auth is included on all plans with no per-connection fees. It uses browser sessions for login, health checks, and eligible automatic reauthentication. These count toward your browser usage and concurrency like any other browser session. Auth sessions are fast, typically 5-30 seconds each, and most website sessions remain valid for days. For example, monitoring 100 auth connections typically costs less than $5/month in browser usage. + +Free users can create up to three vaults. Unlimited vaults are included in paid plans. There are no surcharges to use Kernel's agentic payments products. + Regional browsers are charged at the same usage rates as our default, US-based browsers. - -Free users can create up to three vaults. Unlimited vaults are included in paid plans. There are no surcharges to use Kernel's agentic payments products. + +App invocations are billed for active compute time, not per API call. The invocation rate in [Usage Rates](#usage-rates) is based on the current 4 GB memory allocation at $0.0000166667 per GB-second. + +Billing starts when your code begins executing and stops when it finishes. You aren't charged for queued time, deploying an app, or leaving a deployed app idle. Failed and canceled invocations still accrue charges for the time they ran. + +Browsers created by an invocation are billed separately for their active runtime at the browser rates above. Services your code calls, such as an LLM API, also bill you independently. + +The [app invocation limits](/browsers/concurrency-and-limits#concurrency) are concurrency limits, not a number of invocations included with your plan. diff --git a/info/projects.mdx b/info/projects.mdx index b9f37a88..9757b052 100644 --- a/info/projects.mdx +++ b/info/projects.mdx @@ -5,13 +5,13 @@ description: "Organize resources and isolate access within your Kernel organizat A **Project** is a named container for Kernel resources inside an organization. Use projects to separate environments (like `production` and `staging`), split resources between teams, or isolate customer workloads — each project has its own browsers, profiles, credentials, proxies, extensions, deployments, and browser pools. -## Why Projects? +## Why projects? - **Isolate environments** — keep `production` resources apart from `staging` or experiments. - **Scope access** — issue API keys that can only see resources in one project. - **Concurrency limits** — set an org-wide default cap for every project, or override it per project, so one team or environment can't exhaust your org quota. -## The Default Project +## The default project Every organization has at least one project. Resources that existed before projects were introduced have been moved into a project named **Default**, so your existing browsers, apps, profiles, and other resources continue to work without any changes on your end. @@ -23,7 +23,7 @@ Your organization must always have **at least one active project**. The API retu A project must also be empty before it can be deleted. If active resources remain, the API returns `409 Conflict` with code `project_not_empty`; delete or otherwise remove those resources and retry. Organizations without Projects enabled receive `404 Not Found` with code `projects_disabled` from project-management endpoints. -## Scoping Requests to a Project +## Scoping requests to a project Pass the `X-Kernel-Project-Id` header with a project ID on any API request to scope it to a specific project. Project names are not accepted in this header. Without the header (and without a project-scoped API key), requests act on your organization's **default project**: reads return the default project's resources, and writes create resources in it. @@ -98,7 +98,7 @@ func main() { ``` -## Authentication and Project Scope +## Authentication and project scope ### API keys @@ -112,7 +112,7 @@ API keys can be **org-wide** or **project-scoped**. OAuth tokens (used by the Kernel CLI and MCP server) are **always org-wide**. You cannot bind an OAuth session to a single project. To scope OAuth-authenticated requests, send the `X-Kernel-Project-Id` header with each request — or use the CLI's `--project` flag (see below). -## Using Projects from the CLI +## Using projects from the CLI The Kernel [CLI](/reference/cli/projects) has first-class project support: @@ -136,7 +136,7 @@ kernel projects limits set staging --max-concurrent-sessions 5 Under the hood, `--project` (or the env var) adds the `X-Kernel-Project-Id` header to every authenticated request. It's the recommended way to target a specific project when you're logged in with OAuth (`kernel login`), since OAuth itself is always org-wide. -## Managing Projects +## Managing projects Use the `/org/projects` REST endpoints (or the SDKs' `projects` resource) to manage projects. @@ -297,11 +297,11 @@ if err := client.Projects.Delete(ctx, "proj_abc123"); err != nil { Project deletion is a soft delete. A project that still owns active resources returns `project_not_empty`; the final active project returns `last_active_project`. -## Concurrency Limits +## Concurrency limits Kernel caps how many browsers can run at once, at two levels. A single limit covers both on-demand browsers (`browsers.create()`) and [browser pools](/browsers/pools) — standalone sessions and pool capacity count against the same cap. -- **Organization limit** — the total concurrent browsers allowed across your whole organization, determined by your plan. Every browser session and every browser in a browser pool counts against it. +- **Organization limit** — the total concurrent browsers allowed across your whole organization, determined by your plan. See [concurrency and limits](/browsers/concurrency-and-limits#concurrency) for each plan's limit. Every browser session and every browser in a browser pool counts against it. - **Per-project limits** — optional caps on individual projects, so one team or environment can't consume the entire org limit. Per-project caps come from two places: diff --git a/info/spending-caps.mdx b/info/spending-caps.mdx index 89a35507..f7991f6c 100644 --- a/info/spending-caps.mdx +++ b/info/spending-caps.mdx @@ -168,5 +168,5 @@ If a project cap is higher than the organization cap plus monthly credits, the o - Spending caps bound monthly usage cost. [Concurrency limits](/info/pricing#concurrency-limits) bound simultaneous browser capacity. A spending cap doesn't reserve throughput, and a concurrency limit doesn't bound monthly spend. + Spending caps bound monthly usage cost. [Concurrency limits](/browsers/concurrency-and-limits#concurrency) bound simultaneous browser capacity. A spending cap doesn't reserve throughput, and a concurrency limit doesn't bound monthly spend. diff --git a/info/trust-center.mdx b/info/trust-center.mdx new file mode 100644 index 00000000..5739a8d1 --- /dev/null +++ b/info/trust-center.mdx @@ -0,0 +1,17 @@ +--- +title: "Trust Center" +description: "Where to get Kernel's compliance reports and security artifacts" +--- + +Kernel's compliance artifacts live in the trust center: **[trust.kernel.sh](https://trust.kernel.sh)**. + +What you'll find there: + +- The **SOC 2 Type II** report, available on request. +- Current compliance status. +- The [authorized subprocessor list](https://trust.kernel.sh/subprocessors), referenced by the [DPA](/dpa). +- Security artifacts and questionnaire responses for vendor review. + +For how the program works rather than the paperwork, see [security practices](/security) and the [shared responsibility model](/shared-responsibility-model). For what changes on an Enterprise plan — BAA and zero data retention — see [Enterprise](/info/enterprise). + +Security questions go to [security@kernel.sh](mailto:security@kernel.sh). Reporting a vulnerability? See [vulnerability reporting](/security-vulnerability-reporting). diff --git a/integrations/claude/overview.mdx b/integrations/claude/overview.mdx index a24d6a60..13fea79a 100644 --- a/integrations/claude/overview.mdx +++ b/integrations/claude/overview.mdx @@ -1,5 +1,5 @@ --- -title: "Overview" +title: "Claude" description: "Give Claude a Kernel cloud browser — across Claude Code, Claude Desktop, the Agent SDK, and Managed Agents" --- diff --git a/integrations/computer-use/overview.mdx b/integrations/computer-use/overview.mdx index 0e1e9f8b..e621b1b6 100644 --- a/integrations/computer-use/overview.mdx +++ b/integrations/computer-use/overview.mdx @@ -1,5 +1,5 @@ --- -title: "Overview" +title: "Computer Use" description: "Run computer use agents on Kernel cloud browsers" --- diff --git a/integrations/openai/agents-sdk.mdx b/integrations/openai/agents-sdk.mdx new file mode 100644 index 00000000..0e2351ee --- /dev/null +++ b/integrations/openai/agents-sdk.mdx @@ -0,0 +1,50 @@ +--- +title: "OpenAI Agents SDK" +description: "Give agents built with the OpenAI Agents SDK a KERNEL browser" +--- + + +This is a starter guide. A full walkthrough is coming. + + +The [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) is OpenAI's framework for building agents. The quickest way to give an agent a KERNEL browser is to connect it to the [KERNEL MCP server](/reference/mcp-server), which exposes browser creation, Playwright execution, screenshots, and computer controls as tools. + +## Install + +```bash +pip install openai-agents +``` + +Set `OPENAI_API_KEY` and `KERNEL_API_KEY` in your environment. + +## Connect an agent to KERNEL + +```python Python +import asyncio +import os + +from agents import Agent, Runner +from agents.mcp import MCPServerStreamableHttp + + +async def main(): + async with MCPServerStreamableHttp( + name="kernel", + params={ + "url": "https://mcp.onkernel.com/mcp", + "headers": {"Authorization": f"Bearer {os.environ['KERNEL_API_KEY']}"}, + }, + ) as kernel: + agent = Agent( + name="Browser agent", + instructions="Use the KERNEL tools to create a browser, do the task, then delete the browser.", + mcp_servers=[kernel], + ) + result = await Runner.run(agent, "Go to news.ycombinator.com and list the top 5 story titles.") + print(result.final_output) + + +asyncio.run(main()) +``` + +The MCP server accepts your KERNEL API key as a bearer token. See [MCP authentication](/reference/mcp-server/authentication). diff --git a/integrations/openai/codex.mdx b/integrations/openai/codex.mdx new file mode 100644 index 00000000..18bdcc51 --- /dev/null +++ b/integrations/openai/codex.mdx @@ -0,0 +1,35 @@ +--- +title: "Codex" +description: "Give OpenAI's Codex a KERNEL browser" +--- + + +This is a starter guide. A full walkthrough is coming. + + +[Codex](https://developers.openai.com/codex) is OpenAI's coding agent. You can give it KERNEL know-how with the KERNEL plugin, and KERNEL browsers as tools with the KERNEL MCP server. Use either or both. + +## Install the KERNEL plugin + +The plugin adds [Agent Skills](/skills/overview) for the KERNEL CLI and SDKs, so Codex knows how to create and drive browsers. + +```bash +codex plugin marketplace add kernel/skills +codex plugin add kernel-cli@kernel +codex plugin add kernel-sdks@kernel +``` + +You can also find the KERNEL plugins under **Plugins** in the ChatGPT desktop app after adding the marketplace. + +## Connect the MCP server + +The [KERNEL MCP server](/reference/mcp-server) gives Codex tools to create browsers, run Playwright code, take screenshots, and more. + +```bash +codex mcp add kernel --url https://mcp.onkernel.com/mcp +codex mcp login kernel +``` + +`codex mcp login` opens your browser so you can authorize access to your KERNEL account. To use an API key instead, see [MCP authentication](/reference/mcp-server/authentication). + +Start a Codex session and run `/mcp` to confirm the KERNEL tools are available. diff --git a/integrations/overview.mdx b/integrations/overview.mdx index 2b4af56c..d9dc1370 100644 --- a/integrations/overview.mdx +++ b/integrations/overview.mdx @@ -1,57 +1,165 @@ --- -title: "Overview" +title: "Integrations" +sidebarTitle: "Integrations" +description: "Run Kernel browsers from the agent frameworks, models, and platforms you already use" +mode: "wide" --- -Kernel's browsers are compatible with all browser and Computer Use frameworks. +Kernel browsers work with any tool that speaks the Chrome DevTools Protocol or WebDriver BiDi. The guides below cover the integrations with first-class support. For anything else, see [how you drive the browser](/introduction/control). For every integration from one vendor on one page, see [Claude](/integrations/claude/overview) and [Vercel](/integrations/vercel/overview). -## Universal CDP compatibility +Sections follow the pieces of a browser agent described in [important concepts](/overview/concepts). -Kernel browsers work with any framework or tool that supports the Chrome DevTools Protocol (CDP). This means you can: + + + +## Add a browser to an agent you already use -- **Use any agent framework**: Integrate with popular frameworks like Browser Use, Stagehand, Playwright, Puppeteer, Selenium, and more -- **Connect via CDP**: All browsers expose a CDP WebSocket URL for direct connection -- **No vendor lock-in**: Switch between frameworks or use multiple frameworks simultaneously -- **Standard protocols**: Built on open standards that work with the entire browser automation ecosystem +Give a finished agent or coding tool a Kernel browser, usually through MCP, a plugin, or a config setting. You don't write the loop. -## Computer Use + + + Give Claude Code and Claude Desktop a Kernel browser. + + + Run Anthropic's hosted agent harness against Kernel browsers. + + + Give OpenAI's Codex a Kernel browser with the Kernel plugin and MCP server. + + + Give Replit Agent a Kernel browser. + + + Give your Vercel Eve agent a Kernel browser. + + + Give Vercel's fx coding agent a Kernel browser over MCP. + + + Run Hermes Agent browser tools on Kernel browsers. + + -For vision-language models (VLMs) that predict browser actions from screenshots, Kernel provides [Computer Controls APIs](/browsers/computer-controls) that enable direct mouse, keyboard, and screen interactions. These low-level controls let you: +## Build your own agent -- Capture screenshots to send to your VLM -- Execute predicted actions (clicks, typing, scrolling, dragging) -- Build custom agentic loops with any VLM provider +Agent frameworks for writing the loop yourself, with a Kernel browser as one of its tools. -This approach works with any computer use model, including Anthropic Claude, OpenAI CUA, Google Gemini, and others. + + + Build Claude agents that drive Kernel browsers with playwright execution. + + + Connect agents built with the OpenAI Agents SDK to Kernel browsers over MCP. + + + Give AI SDK agents Kernel browser tools. + + -## Popular Framework Integrations + +## Computer use models -Kernel provides detailed guides for popular agent frameworks: +Run a vision model's screenshot-and-act loop against a Kernel browser. See the [computer use overview](/integrations/computer-use/overview) for how the loop works. -- **[Agent Browser](/integrations/vercel/agent-browser)** - Browser automation CLI for AI agents -- **[fx](/integrations/vercel/fx)** - Give Vercel's fx coding agent a Kernel cloud browser via MCP -- **[Browser Use](/integrations/browser-use)** - AI browser agent framework -- **[e2e](/integrations/e2e)** - Run agentic end-to-end tests in Kernel cloud browsers -- **[Hermes Agent](/integrations/hermes-agent)** - Run Hermes browser tools on Kernel cloud browsers -- **[Claude Code and Desktop](/integrations/claude/claude-code-and-desktop)** - Give the Claude apps a Kernel browser via the marketplace plugin or MCP -- **[Claude Agent SDK](/integrations/claude/claude-agent-sdk)** - Run Claude Agent SDK automations in cloud browsers -- **[Claude Managed Agents](/integrations/claude/claude-managed-agents)** - Run Anthropic's hosted agent harness against cloud browsers -- **[Docker Sandboxes](/integrations/docker-sandboxes)** - Give agents in Docker Sandboxes a Kernel cloud browser with the Kernel kit -- **[Replit](/integrations/replit)** - Give Replit Agent a Kernel cloud browser -- **[Stagehand](/integrations/stagehand)** - AI browser automation with natural language -- **[Terraform](/integrations/terraform)** - Manage durable Kernel infrastructure as code -- **[Computer Use (Anthropic)](/integrations/computer-use/anthropic)** - Claude's computer use capability -- **[Computer Use (OpenAI)](/integrations/computer-use/openai)** - OpenAI's computer use capability -- **[Computer Use (Gemini)](/integrations/computer-use/gemini)** - Gemini's computer use capability -- **[Computer Use (OpenAGI)](/integrations/computer-use/openagi)** - OpenAGI's computer use capability -- **[Computer Use (Yutori)](/integrations/computer-use/yutori)** - Yutori Navigator n1.5 pixels-to-actions model -- **[Laminar](/integrations/laminar)** - Observability and tracing for AI browser automations -- **[wallets](/integrations/wallets/overview)** - connect payment methods through native wallet integrations -- **[Val Town](/integrations/valtown)** - Serverless function runtime -- **[Stripe Projects](/integrations/stripe-projects)** - Provision Kernel plans and API keys via the Stripe Projects CLI -- **[Vercel](https://github.com/onkernel/vercel-template)** - Deploy browser automations to Vercel -- **[Web Bot Authentication](/browsers/bot-detection/web-bot-auth)** - Create signed Chrome extensions for web bot authentication -- **[1Password](/integrations/1password)** - Use credentials from your 1Password vaults for Managed Auth + + + Claude computer use. + + + OpenAI computer-using agent. + + + Gemini 2.5 Computer Use. + + + Yutori Navigator n1.5 pixels-to-actions model. + + + OpenAGI Lux computer use model. + + + Tzafon Northstar CUA Fast. + + -## Custom Integrations +## Browser automation frameworks -Kernel works with any tool that supports CDP. Check out our [browser control guide](/introduction/control) to learn how to connect any other agent framework. +Drive the page itself — navigate, click, fill, extract — against a Kernel browser. + + + + Run Playwright code inside the browser's VM, or connect over CDP. + + + Vercel's browser automation CLI for AI agents. + + + Mix code and natural language browser automation on Kernel. + + + Drive Kernel browsers with a WebDriver BiDi automation framework. + + + Run agentic and deterministic end-to-end tests in Kernel browsers. + + + Run Browser Use agents on Kernel browsers. + + + +## Credentials, identity, and payments + +Give the browser what it needs to log in, prove who it is, and check out, without handing secrets to your agent. See [authentication](/auth/overview) and [payments](/browsers/payments) for how these work end to end. + + + + Use credentials from your 1Password vaults. + + + Approve a one-use payment credential for a browser checkout. + + + Approve browser checkouts against an enrolled payment method. + + + Sign your agent's requests with Cloudflare's Web Bot Auth, so participating sites can verify its identity. + + + +## Deploy and provision + +Provision and run Kernel from the platforms you deploy on. + + + + Add Kernel to a Vercel project through the Marketplace. + + + Deploy browser automations to Vercel from a starter template. + + + Provision Kernel browsers and plans with the Stripe Projects CLI. + + + Manage durable Kernel infrastructure with Terraform. + + + Run browser automations from Val Town's serverless runtime. + + + Give agents running in Docker Sandboxes a Kernel browser. + + + +## Observability + +Send traces, evaluations, and browser telemetry to the tools you already monitor with. + + + + Trace and evaluate browser agents with Laminar. + + + Export a session's telemetry events to any OTLP/HTTP backend. + + diff --git a/integrations/stripe-projects.mdx b/integrations/stripe-projects.mdx index 2adc066e..fd1caef3 100644 --- a/integrations/stripe-projects.mdx +++ b/integrations/stripe-projects.mdx @@ -1,5 +1,5 @@ --- -title: "Overview" +title: "Stripe Projects" description: "Provision Kernel cloud browsers and plans through the Stripe Projects CLI" --- diff --git a/integrations/vercel/foreman.mdx b/integrations/vercel/foreman.mdx deleted file mode 100644 index 4da727ae..00000000 --- a/integrations/vercel/foreman.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "Foreman" -description: "Give your Foreman agent a Kernel cloud browser" ---- - -## Overview - -[Foreman](https://ask-foreman.dev) is a free, open-source software factory: specialized AI agents classify, plan, implement, and review work pulled from GitHub issues, Linear, CI failures, and more, then push draft PRs for a human to approve. Nothing ships without you — Foreman stops at the draft PR. - -Foreman is built on [Vercel Eve](https://vercel.com/eve), so it mounts extensions the same way any Eve agent does. - -### Foreman + Kernel - -Mounting Kernel's [Eve extension](/integrations/vercel/eve-extension) gives Foreman's implementation agent a real cloud browser, so it can go beyond reading code to reproduce bugs and verify fixes in flows that only break behind authentication: - -- **Sign-in, not just code review** — the agent drives an authenticated browser session to reproduce the bug the way a signed-in user would hit it. -- **Per-user identity** — each teammate authenticates through their own Vercel Connect consent, so the browser acts as them rather than a shared credential. -- **An approval gate** — Foreman parks its first browser action per session for the person driving it, before it acts inside a logged-in session. - -### Steps - -1. **Install the software factory template** — deploy [`vercel-labs/eve-software-factory-template`](https://github.com/vercel-labs/eve-software-factory-template) so Foreman is running against your repo. -2. **Add the Kernel extension** — run `eve add extension/kernel` to mount `@onkernel/eve-extension`. -3. **Add a sign-in approval gate** — wire the browser connection through Vercel Connect so it authenticates as you, and require your approval before its first action in a signed-in session, via Eve's `once()` approval (`eve/tools/approval`). That's what lets the implementation agent reproduce a bug behind auth instead of just reading the code. - - -Do not mount the Kernel 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. - - -The copy prompt below drives your coding agent through steps 2 and 3. - -## Quickstart prompt - -import { CopyPromptButton } from '/snippets/copy-prompt-button.jsx'; - -Paste this into your coding agent to add the Kernel browser to your Foreman repo. It registers the `@onkernel/eve-extension` mount, wires it to Vercel Connect instead of an API key, shadows the browser connection with an approval gate, and holds the tool allowlist to the seven tools it ships with. - - - -## Related - -- [Eve Extension](/integrations/vercel/eve-extension) -- [Vercel Marketplace Integration](/integrations/vercel/marketplace) -- [Managed Auth](/auth/managed-auth) diff --git a/integrations/vercel/overview.mdx b/integrations/vercel/overview.mdx index b42b31a9..4d849a87 100644 --- a/integrations/vercel/overview.mdx +++ b/integrations/vercel/overview.mdx @@ -1,5 +1,5 @@ --- -title: "Overview" +title: "Vercel" description: "Integrate Kernel with Vercel for seamless browser automation in your web applications" --- diff --git a/integrations/wallets/agentcard.mdx b/integrations/wallets/agentcard.mdx index 9c50e37a..b390875c 100644 --- a/integrations/wallets/agentcard.mdx +++ b/integrations/wallets/agentcard.mdx @@ -1,5 +1,5 @@ --- -title: "Agentcard" +title: "AgentCard" description: "Use Agentcard to approve browser checkouts against an enrolled payment method" --- diff --git a/integrations/wallets/overview.mdx b/integrations/wallets/overview.mdx index b23fd4cf..e48f15e9 100644 --- a/integrations/wallets/overview.mdx +++ b/integrations/wallets/overview.mdx @@ -1,5 +1,5 @@ --- -title: "Overview" +title: "Wallets" description: "Connect user wallets through KERNEL's native integrations" --- diff --git a/integrations/wallets/stripe-link.mdx b/integrations/wallets/stripe-link.mdx index 187332c1..69f7347c 100644 --- a/integrations/wallets/stripe-link.mdx +++ b/integrations/wallets/stripe-link.mdx @@ -1,5 +1,5 @@ --- -title: "link by stripe" +title: "Link by Stripe" description: "use link by stripe to approve a one-use payment credential for a browser checkout" --- diff --git a/introduction/configure.mdx b/introduction/configure.mdx new file mode 100644 index 00000000..cf0f8543 --- /dev/null +++ b/introduction/configure.mdx @@ -0,0 +1,122 @@ +--- +title: "Configure" +sidebarTitle: "Overview" +description: "Create a browser, pick its shape, and choose what it carries onto a site" +mode: "wide" +--- + +A KERNEL browser works with no configuration: create one and drive it. This page covers the settings most agents touch at creation time. The rest of Configure covers the features that decide whether an agent gets through a real site: stealth, proxies, profiles, vaults, authentication, and payments. + +## Create a browser + + +```typescript TypeScript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); + +const browser = await kernel.browsers.create(); +console.log(browser.session_id, browser.browser_live_view_url); +``` + +```python Python +from kernel import Kernel + +kernel = Kernel() + +browser = kernel.browsers.create() +print(browser.session_id, browser.browser_live_view_url) +``` + +```go Go +package main + +import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" +) + +func main() { + ctx := context.Background() + client := kernel.NewClient() + + browser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{}) + if err != nil { + panic(err) + } + fmt.Println(browser.SessionID, browser.BrowserLiveViewURL) +} +``` + +```bash CLI +kernel browsers create +``` + + +The response includes everything you need to drive the browser: `session_id`, `cdp_ws_url`, `webdriver_ws_url`, and `browser_live_view_url`. See [create a browser](/introduction/create) for the full walkthrough, including creating from a [browser pool](/browsers/pools). + +## Pick a browser type + +| Type | When to use it | How to set it | +| --- | --- | --- | +| **Headful** (default) | Agents on real sites. It has a real display, so [live view](/browsers/live-view) and [replays](/browsers/replays) work and bot detectors see a normal browser. 8 GB of memory by default. | Nothing to set | +| **[Headless](/browsers/headless)** | Short-lived or highly concurrent jobs that don't need to be watched. Lighter, at 1 GB by default, but some bot detectors notice it. | `headless: true` | +| **[GPU-accelerated](/browsers/gpu-acceleration)** | WebGL, video, and canvas-heavy sites. Headful only, doesn't support standby, and has its own usage rate. | `gpu: true` | + +## Set common options + + +```typescript TypeScript +const browser = await kernel.browsers.create({ + viewport: { width: 1280, height: 800 }, + timeout_seconds: 300, +}); +``` + +```python Python +browser = kernel.browsers.create( + viewport={"width": 1280, "height": 800}, + timeout_seconds=300, +) +``` + + +- **[Viewport](/browsers/viewport):** defaults to 1920x1080 at 25Hz. A custom viewport restarts Chromium on creation, so use a [browser pool](/browsers/pools) if you need it to be instant. +- **[Termination and timeouts](/browsers/termination):** `timeout_seconds` sets how long a browser can sit in standby before KERNEL deletes it. It defaults to 60 seconds and can be up to 72 hours. Delete browsers explicitly when you're done; Playwright's `browser.close()` doesn't delete them. + +## More browser settings + +Often agents don't require these, but they're there when you do: + +- **[Regions](/browsers/regions):** run browsers in `us-east`, `eu-west`, or `ap-southeast`, closer to your code and your users. +- **[Extensions](/browsers/extensions):** load unpacked Chrome extensions into a browser. +- **[Chrome policies](/browsers/chrome-policies):** apply Chrome enterprise policies, such as startup pages and bookmarks. +- **[Private networking](/browsers/private-networking):** reach services behind a VPN or tunnel from inside the browser session. + +## What to configure next + + + + Anti-detection defaults, stealth mode, CAPTCHA handling, and Web Bot Auth. + + + Route traffic through datacenter, ISP, residential, or mobile IPs, or bring your own. + + + Save cookies, storage, and logins from one session and load them into the next. + + + Store credentials and payment items that a browser fills into a page without your agent reading them. + + + Fill logins from a vault, or let managed auth handle the login and attempt to reauthenticate eligible connections. + + + Let agents complete checkouts through a wallet without handling raw card details. + + + Get browser and proxy settings that have already worked on the site you're automating. + + diff --git a/introduction/control.mdx b/introduction/control.mdx index 5ec902ce..dfe3af1f 100644 --- a/introduction/control.mdx +++ b/introduction/control.mdx @@ -1,11 +1,36 @@ --- title: "Control" -description: "Drive the browser with computer use, playwright execution, CDP, or WebDriver BiDi" +sidebarTitle: "Overview" +description: "Choose a control surface and where your agent loop runs" --- -Kernel browsers expose four ways to drive a session. For agents, we recommend starting with playwright execution and falling back to computer use, here's our guide: [playwright w/ computer use fallback](/browsers/playwright-computer-use-fallback). +You make two choices before you write any automation. They're independent, but the first constrains the second: -Both run co-located with the browser and avoid the bot-detection surface a direct CDP connection introduces. +1. **How you drive the browser** — the control surface your code or model uses to act on the page. +2. **Where the loop runs** — the machine your decision-making code runs on, relative to the browser. + + + +## 1. How you drive the browser + +KERNEL browsers accept several control surfaces. Pick by what's driving the page, not by what you already know. + +| Surface | Use it when | Trade-off | +| --- | --- | --- | +| [Playwright execution](/browsers/playwright-execution) | **Default.** You know what to do on the page — navigate, fill, extract, upload. | Needs a selector or DOM path that exists, and each call is stateless. | +| [Computer controls](/browsers/computer-controls) | **Recommended fallback.** A model is looking at pixels, or the page can't be driven programmatically. | Slower per step, and the model has to see the state to act. | +| [WebMCP](/browsers/webmcp) | The site exposes structured tools for the action you need. | Only works on sites that register tools. | +| [Browser REPL](/browsers/repl) | An agent writes its own helpers and reuses them across turns. State persists across calls until the REPL resets. | JavaScript only. | +| CDP | You have an existing Playwright, Puppeteer, or CDP codebase to point at Kernel. | Adds a protocol fingerprint and a network hop. | +| WebDriver BiDi | You need the W3C standard protocol. | Smaller client ecosystem. | + +For agents, start with [playwright execution with a computer use fallback](/browsers/playwright-computer-use-fallback): script the deterministic steps, and hand the page to a computer use model when a step doesn't respond to a selector. + +### Why the choice matters on hardened sites + +CDP is what Playwright and Puppeteer speak, and anti-bot vendors scan for its signatures. Computer controls carry no CDP connection, so there's no protocol fingerprint to leak. That makes them the stronger option on sites with aggressive detection. How much this matters is site-specific, so test before you commit — see [bot anti-detection](/browsers/bot-detection/overview). + +### Control surface examples @@ -210,85 +235,61 @@ fmt.Println(response.Result) -## Why computer use for agents +## 2. Where the loop runs + +Your loop is whatever decides the next action: a script, an agent, or a model. It can run in three places. + + + + Connect to `cdp_ws_url` or `webdriver_ws_url` from wherever your code already runs. Any CDP client works, and there's no lock-in. + + **Costs:** a network round trip per action, disconnects to handle, screenshot and DOM bandwidth, and the CDP fingerprint above. It's fine for low-frequency or deterministic work, and it hurts most in a vision loop. + + + Send code, not commands. Each call runs in the browser's VM against the live session, so an agent can drive the page turn by turn — one tool call per step, structured data back. + + **Costs:** each call is stateless, so the code you send has to be self-contained. There's nothing to install and no connection to manage. + + + Run JavaScript in a persistent runtime inside the browser's VM. Variables, helpers, and state carry across calls, so an agent can define what it needs once and build on it turn by turn. See [Browser REPL](/browsers/repl). + + **Costs:** JavaScript only, and state is lost when the REPL resets. + + + Deploy the whole agent next to the browser with the [code execution platform](/apps/develop), invoked on demand or on a schedule, with no infrastructure of your own. -Kernel's computer controls are built to match how computer-use models were trained — the same primitives the model emits (screenshot, click at coords, type, key, scroll, drag) map 1:1 onto the API. There's no harness translating model output into framework calls. + **Costs:** your agent has to be deployable as a Kernel app. It's worth it once the automation is long-running, stateful, or triggered by events rather than by a person. + + -- **Native fit.** Screenshot, click, type, key, scroll, drag — the primitives the model already speaks. -- **Faster screenshots.** Captures bypass CDP, which removes the largest source of latency in a vision loop. -- **Better against bot detection.** No CDP connection means no CDP fingerprint to leak. Pairs naturally with [stealth mode](/browsers/bot-detection/stealth) and [residential proxies](/proxies/residential). -- **Human-like input.** OS-level events with Bézier-curve mouse paths, variable typing speed, and configurable mistype rate. -- **Not DOM-limited.** Screenshots capture the full VM, so the agent can see and interact with native dialogs, canvas elements, iframes, and PDFs — not just things you can address with a selector. +### Where computer use fits -## Why playwright execution over a direct CDP connection +A computer use agent answers the first question, not the second — it still has to run its loop somewhere. Because every turn ships a screenshot instead of a small script, running that loop off-platform costs far more than it does for a Playwright-driven agent: you pay image bandwidth and a round trip on every step. That makes computer use the strongest case for running your loop next to the browser. Model inference stays with the model vendor either way. -If you're reaching for Playwright, prefer the execution API over `connectOverCDP`. Same Playwright API you already know, none of the setup. +### Putting it together -- **Run from anywhere.** No `playwright` package to version-pin, no Chromium download, no CDP connection to manage. Send the code, get the result. -- **Co-located with the browser.** Code runs in the same VM as the browser — no network hop between your script and the page, fewer flakes. -- **Patchright by default.** Hardened against bot detection out of the box. -- **Full Playwright API.** `page`, `context`, and `browser` are all in scope. Anything Playwright can do — DOM queries, file uploads, full-page screenshots — works here. -- **Returns values.** `return` from your code and the result comes back in the response. Easy to use as an agent tool. +| Your automation | Control surface | Where the loop runs | +| --- | --- | --- | +| Scheduled scrape of a known page | Playwright execution | Anywhere — one call, one result | +| Agent doing multi-step work on a normal site | Playwright execution, computer use fallback | Playwright execution API, or the code execution platform once it's long-running | +| Agent on a site with aggressive detection | Computer controls | Code execution platform | +| Existing Playwright suite you're migrating | CDP | Your own CI, then move hot paths to playwright execution | ## Computer use + playwright execution -Computer controls drive the browser the way a person would — they don't speak the programmatic API surface. Anything you'd reach for the DOM or Playwright client for (reading text and attributes, `page.goto`, file uploads, cookie or storage access, switching tabs) belongs on the [playwright execution](/browsers/playwright-execution) side. The recommended pattern for agents is computer controls for interaction, playwright execution as a tool the agent can call when it needs structured data or a programmatic action. - - -```typescript Typescript/Javascript -const response = await kernel.browsers.playwright.execute( - kernelBrowser.session_id, - { - code: ` - const rows = await page.$$eval('table tr', (trs) => - trs.map((tr) => Array.from(tr.querySelectorAll('td')).map((td) => td.textContent)) - ); - return rows; - `, - }, -); - -console.log(response.result); -``` - -```python Python -response = kernel.browsers.playwright.execute( - id=kernel_browser.session_id, - code=""" - const rows = await page.$$eval('table tr', (trs) => - trs.map((tr) => Array.from(tr.querySelectorAll('td')).map((td) => td.textContent)) - ); - return rows; - """, -) +Computer controls drive the browser the way a person would — they don't speak the programmatic API surface. Anything you'd reach for the DOM or Playwright client for (reading text and attributes, `page.goto`, file uploads, cookie or storage access, switching tabs) belongs on the [playwright execution](/browsers/playwright-execution) side. When computer use is driving, expose playwright execution to the agent as a tool it can call for structured data or a programmatic action. For the full pattern in the other direction — playwright execution first, computer use when a step doesn't respond to a selector — see [playwright with computer use fallback](/browsers/playwright-computer-use-fallback). -print(response.result) -``` +## Lower-level access -```go Go -response, err := client.Browsers.Playwright.Execute( - ctx, - kernelBrowser.SessionID, - kernel.BrowserPlaywrightExecuteParams{ - Code: ` - const rows = await page.$$eval('table tr', (trs) => - trs.map((tr) => Array.from(tr.querySelectorAll('td')).map((td) => td.textContent)) - ); - return rows; - `, - }, -) -if err != nil { - panic(err) -} +For work that isn't driving the page, you can also reach the browser's VM directly: -fmt.Println(response.Result) -``` - +- **[Browser curl](/browsers/curl):** send HTTP requests through the browser's network stack, with its cookies and proxy. +- **[SSH](/browsers/ssh):** open a shell in the browser's VM, or forward a local port into it. ## Going deeper - [Computer Controls reference](/browsers/computer-controls) — every mouse, keyboard, and screen primitive. - [Playwright Execution reference](/browsers/playwright-execution) — the full execution surface, return values, and timeouts. +- [Browser REPL reference](/browsers/repl) — persistence across calls, browser control helpers, and WebMCP helpers. - [Computer use integrations](/integrations/computer-use/anthropic) — drop-in examples for Anthropic, Gemini, OpenAI, and more. -- [Network access](/info/network-access) lists the domains and ports to allow for API, CDP, and WebDriver BiDi connections. +- [Firewall allowlist](/info/network-access) lists the domains and ports to allow for API, CDP, and WebDriver BiDi connections. diff --git a/introduction/create.mdx b/introduction/create.mdx index 4ee4d5af..8629f658 100644 --- a/introduction/create.mdx +++ b/introduction/create.mdx @@ -91,7 +91,7 @@ Most of what you'll tune at creation time falls into four buckets: `browsers.create()` boots a browser for you on the spot. That's the right call while you're building, and for workloads that run occasionally. -Once you're running the same task repeatedly — or more than a handful at a time — create a [browser pool](/browsers/pools) instead. A browser pool holds browsers that are already booted with your configuration applied, so `acquire` hands you one that's ready to drive rather than starting one from scratch. Two things get faster: configurations that restart Chromium on creation (custom viewports, extensions, kiosk mode) are already applied, and acquiring from a browser pool sidesteps the [rate limit](/info/pricing#rate-limiting) on browser creation that you'll otherwise hit at volume. +Once you're running the same task repeatedly — or more than a handful at a time — create a [browser pool](/browsers/pools) instead. A browser pool holds browsers that are already booted with your configuration applied, so `acquire` hands you one that's ready to drive rather than starting one from scratch. Two things get faster: configurations that restart Chromium on creation (custom viewports, extensions, kiosk mode) are already applied, and acquiring from a browser pool sidesteps the [rate limit](/browsers/concurrency-and-limits#rate-limits) on browser creation that you'll otherwise hit at volume. ```typescript Typescript/Javascript @@ -133,7 +133,7 @@ kernel browser-pools acquire checkout-pool ``` -An acquired browser returns the same fields as one you created directly, so the rest of your code is identical. Idle browsers in a browser pool aren't billed — you pay only while a browser is acquired and running — though browser pool capacity does count against your [concurrency limit](/info/pricing#concurrency-limits). +An acquired browser returns the same fields as one you created directly, so the rest of your code is identical. Idle browsers in a browser pool aren't billed — you pay only while a browser is acquired and running — though browser pool capacity does count against your [concurrency limit](/browsers/concurrency-and-limits#concurrency). ## Lifecycle diff --git a/introduction/manage.mdx b/introduction/manage.mdx new file mode 100644 index 00000000..ddfdb5de --- /dev/null +++ b/introduction/manage.mdx @@ -0,0 +1,35 @@ +--- +title: "Manage" +sidebarTitle: "Overview" +description: "Organize, secure, and govern how your team uses KERNEL" +mode: "wide" +--- + +Management settings apply across your organization rather than to a single browser: how resources are split between teams and environments, who and what can call the API, what happened and when, and how much you spend. + + + + Separate environments, teams, or customers, each with its own browsers, profiles, credentials, and limits. + + + Create, scope, rotate, and delete the keys your code and agents use. + + + Set a monthly spending guardrail for your organization, a project, or both. + + + A year of API request history across your organization, searchable and exportable on Start-Up and Enterprise. + + + The KERNEL domains and ports to allow if your firewall restricts outbound traffic. + + + +## Multi-tenant setups + +If you run KERNEL on behalf of your own customers, combine these pieces so each customer is isolated and capped: + +- **One [project](/info/projects) per customer.** Each project has its own browsers, profiles, credentials, proxies, and deployments. +- **A [project-scoped API key](/info/api-keys) per customer workload.** A project-scoped key can only reach resources in its project. +- **A [spending cap](/info/spending-caps) and a [concurrency limit](/info/projects#concurrency-limits) per project.** One customer's usage can't exhaust your budget or your organization's browser limit. +- **One [profile](/browsers/profiles) per end user.** Each user's logins and browser state stay separate, inside their customer's project. diff --git a/introduction/observe.mdx b/introduction/observe.mdx index 167e470f..b94194e0 100644 --- a/introduction/observe.mdx +++ b/introduction/observe.mdx @@ -1,5 +1,6 @@ --- title: "Observe" +sidebarTitle: "Overview" description: "Watch your agent work, debug what went wrong" --- diff --git a/introduction/scale.mdx b/introduction/scale.mdx index 53947ebb..052fa562 100644 --- a/introduction/scale.mdx +++ b/introduction/scale.mdx @@ -1,52 +1,75 @@ --- title: "Scale" -description: "Recommended practices for scaling in production" +sidebarTitle: "Overview" +description: "Plan around your limits, keep browsers fast, and decide whether a browser pool fits" --- -## Overview -This guide covers how to run Kernel in production at scale — which architecture to build around browser creation, and when to reach for a browser pool. It assumes you're comfortable [creating](/introduction/create) and [controlling](/introduction/control) browsers; for the mechanics of standing up a pool and acquiring from it, see [Browser Pools](/browsers/pools). +Scaling an agent on KERNEL comes down to three questions, in this order: how many browsers you can run and create, how fast each one starts, and whether your workload needs a browser pool. Most workloads scale on on-demand browsers alone. This guide assumes you're comfortable [creating](/introduction/configure) and [controlling](/introduction/control) browsers. -## Why a browser pool + +## 1. Know your limits -A [browser pool](/browsers/pools) keeps a set of identically-configured browsers ready for immediate use. Compared to creating browsers on demand, it gives you: +Three limits shape a workload at scale, and each is covered in [concurrency and limits](/browsers/concurrency-and-limits): -- **Low-latency acquisition** — the browser is already booted with your configuration applied (including settings like custom viewports, extensions, and kiosk-mode live view that otherwise [restart Chromium](/browsers/performance#troubleshooting-latency) on a fresh browser), so `acquire` hands you one that's ready to drive. -- **Reserved, pre-configured capacity** — a fixed set of browsers on your exact configuration, ready before traffic arrives. -- **Higher creation throughput** — acquiring from a pool isn't subject to the [rate limit](/info/pricing#rate-limiting) on `browsers.create()` that high-volume workloads hit. +- **Concurrency:** how many browsers can exist at once across your organization. Browsers in [standby](/browsers/standby) still count, so delete browsers when a task finishes to free the slot. +- **Create rate:** how fast you can create new browsers. Exceeding it returns `429 Too Many Requests`, which the SDKs retry automatically. +- **Per-browser resources:** how much memory each browser has, which caps how many tabs and how heavy a page one browser can handle. -The tradeoff: a browser pool counts against your concurrency limit whether or not its browsers are currently acquired — a pool sized to 40 holds 40 of your limit. Idle pooled browsers aren't billed, but they hold the slot. +Each plan has set limits, and they go up when you [upgrade your plan](/info/pricing). Enterprise limits are custom. Use [project concurrency limits](/info/projects#concurrency-limits) to split one organization's limit across teams or environments. -## When to use a pool vs on-demand +## 2. Keep browsers fast -Reach for a **browser pool** when: +A browser is created in about 30ms at P50 and 105ms at P99 ([performance](/browsers/performance)). Most slow starts come from configuration rather than load: custom viewports, extensions, and kiosk mode restart Chromium on creation and add seconds. Check [troubleshooting latency](/browsers/performance#troubleshooting-latency) before reaching for anything else, and run your code next to the browser with [Playwright execution](/browsers/playwright-execution) or the [code execution platform](/apps/develop) to cut the time each action takes. -- you're running the same workload repeatedly, in production -- acquisition latency matters — a cold start is unacceptable (for example, a synchronous, user-facing action) -- traffic is steady or high-frequency enough to keep the browser pool utilized -- you're hitting the `browsers.create()` rate limit at volume + +## 3. Decide between on-demand browsers and a browser pool + +We recommend defaulting to on-demand browsers, both when you're getting started and as you scale. Browser pools fit a specific type of workload, described below. Stick with **on-demand `browsers.create()`** when: -- volume is low, bursty, one-off, or you're still developing -- each session needs a different configuration (a pool is one fixed config) +- you're still building +- your configuration changes per user (a pool is one fixed config) - you need a GPU browser (not available in pools) -Concurrency and request patterns are how you *size* a pool once you've decided to use one — not a threshold that gates whether pools are worth it. Even a small pool pays off when acquisition latency matters and demand is steady. +Reach for a **browser pool** when: + +- you've built and scaled your workload, and every run uses the same workload attributes +- you're hitting the `browsers.create()` rate limit at volume +- you need the lowest possible acquisition latency (for example, a heavily customized browser config) +- traffic is steady or high-frequency enough to keep the browser pool utilized + + + If you're on an Enterprise plan, speak with your account manager about applicable rate limits for `browsers.create()` and what's best for your workloads. + + + +### What a browser pool gives you + +A [browser pool](/browsers/pools) keeps a set of identically-configured browsers ready for immediate use. Compared to creating browsers on demand, it gives you: + +- **Lowest-latency acquisition** — the browser is already booted with your configuration applied (including settings like custom viewports, extensions, and kiosk-mode live view that otherwise [restart Chromium](/browsers/performance#troubleshooting-latency) on a fresh browser), so `acquire` hands you one that's ready to drive. +- **Reserved, pre-configured capacity** — a fixed set of browsers on your exact configuration, ready before traffic arrives. +- **Higher creation throughput** — acquiring from a pool isn't subject to the [rate limit](/browsers/concurrency-and-limits#rate-limits) on `browsers.create()` that high-volume workloads hit. -## Sizing +The tradeoff: a browser pool counts against your concurrency limit whether or not its browsers are currently acquired — a pool sized to 40 holds 40 of your limit. Idle pooled browsers aren't billed, but they hold the slot. + + +### Sizing a pool Watch `available_count` and target 10–20% available under normal load, resizing before traffic peaks rather than during them. See [Sizing a browser pool](/browsers/pools#sizing-a-browser-pool) for the full guidance. ## Architecture patterns -### Direct browser creation (POC) + +### On-demand creation -For proof-of-concept work and early production systems with modest concurrency needs, creating browsers on-demand is the simplest approach. +Creating a browser per task is the simplest approach. It's the right fit while you're building and when each task needs its own configuration. **When to use:** -- Low or unpredictable volume -- Infrequent or one-off workloads - Early development and testing +- Configuration that changes per user or per task +- GPU browsers @@ -84,9 +107,10 @@ async function processTask(taskData: any) { ``` -### Single browser pool (scaling) + +### Single browser pool -For production systems with consistent, high-frequency workloads, a browser pool allows you to access higher concurrency plus predictable performance. +For production workloads that run on the same configuration every time, a browser pool hands you ready-to-drive browsers, and acquiring from it isn't subject to the `browsers.create()` rate limit. **When to use:** - Consistent, high-frequency workloads on a fixed configuration @@ -151,12 +175,13 @@ async function processTask(taskData: any) { - Always release browsers in a `finally` block to prevent browser pool exhaustion - Set `acquire_timeout_seconds` based on your SLA requirements -### Queue-based processing (high scale) + +### Queue-based processing -For systems exceeding browser pool capacity or with unpredictable bursts, implement a task queue to manage workloads gracefully. +When request volume exceeds your concurrency or traffic arrives in unpredictable bursts, put a task queue in front of your browsers. The example below acquires from a browser pool; the same pattern works on demand, with `browsers.create()` in place of `acquire` and `deleteByID` in place of `release`. **When to use:** -- Request volume exceeds a single browser pool's capacity +- Request volume exceeds your available concurrency - Highly variable traffic patterns - Need to prioritize certain tasks - Want to decouple request ingestion from processing @@ -164,8 +189,9 @@ For systems exceeding browser pool capacity or with unpredictable bursts, implem ```typescript -import { Queue } from 'bullmq'; // or any queue system +import { Queue, Worker } from 'bullmq'; // or any queue system import Kernel from '@onkernel/sdk'; +import { chromium } from 'playwright'; const kernel = new Kernel(); const POOL_NAME = 'production-pool'; diff --git a/overview/concepts.mdx b/overview/concepts.mdx new file mode 100644 index 00000000..2625a253 --- /dev/null +++ b/overview/concepts.mdx @@ -0,0 +1,61 @@ +--- +title: "How KERNEL Fits Between Your Agent and the Internet" +sidebarTitle: "Important Concepts" +description: "The agent framework decides what to do; KERNEL provides the browser infrastructure that carries it out on real websites" +mode: "wide" +--- + +A browser agent has three layers. The **agent framework** decides what to do: it runs the loop that asks a model for the next action and carries out the tool calls the model returns. **Browser infrastructure** runs the browser that performs those actions. **The internet** is the set of websites the agent works on. KERNEL provides the browser infrastructure, underneath whichever agent framework you use. + +Knowing which layer does what tells you where a feature belongs and which piece to change when something goes wrong. + + + an agent framework, holding the model, system prompt, tools, skills, and browser automation framework, drives KERNEL browser infrastructure, which carries the chromium vm, stealth, proxies, profiles, auth, and payments, and connects to the internet over https. + + +## Agent framework + +The agent framework, or harness, runs the loop: it sends context to the model, runs the tool call the model returns, feeds the result back, and repeats until the task is done. You either build your own with a framework, such as the [Claude Agent SDK](/integrations/claude/claude-agent-sdk), the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/), or the [Vercel AI SDK](/integrations/vercel/ai-sdk), or use a finished agent that already has one, such as [Claude Code](/integrations/claude/claude-code-and-desktop), [Codex](https://developers.openai.com/codex), or [Replit](/integrations/replit). + +A harness's key pieces include: + +- **Model:** decides the next action from the system prompt, the conversation, tool results, and screenshots. It doesn't drive the browser itself: it returns a tool call and the harness carries it out. +- **System prompt:** the instructions sent with every request to the model: its role, its rules, and the format of its answers. +- **Tools:** functions the model can ask the harness to call, like "navigate to this URL", "click here", or "run this code". +- **Skills:** instructions and reference files the agent loads only when a task needs them, unlike the system prompt, which is sent every turn. +- **Browser automation framework:** turns tool calls into actions on the page, through the DOM with selectors (Playwright, Puppeteer) or through the screen with clicks at coordinates (computer use). Most agents combine the two: DOM actions for most steps, and computer use where the DOM doesn't cooperate. + +## Browser infrastructure + +Browser infrastructure is where the agent's decisions actually get carried out. The agent framework decides to open a page, fill a form, or click a button; browser infrastructure runs the browser that does it, and gives the agent what it needs to reach and interact with real websites. Its key pieces include: + +- **Browser:** the Chromium instance the agent drives, isolated from every other session. +- **Stealth and proxies:** anti-detection, CAPTCHA handling, and an IP address that fits the site, so the browser isn't blocked. +- **Credentials and state:** saved logins, credentials, and payment methods the browser can use without exposing them to the model. +- **Observability:** live view, replays, and telemetry, so you can see what happened when something goes wrong. +- **Scale:** running many browsers concurrently, and absorbing bursts when an agent creates a large number of browsers at once. + +## The internet + +Real websites weren't built for agents. They check for bots, and the useful pages often sit behind logins that need passwords, MFA codes, or payment details. Those credentials have to be used without exposing them to the model or leaking them into logs. The agent framework decides what to do; browser infrastructure is what gets it through, securely. + +## Which piece to change + +| What you see | Where to look | +| --- | --- | +| The agent picks the wrong action or ignores a rule | The model or the system prompt | +| The agent doesn't know how to use an API or a site | Skills | +| The agent can't do something at all | Tools | +| A selector breaks or a page action fails | The browser automation framework, the site's behavior, or the browser's state. Try [computer controls](/browsers/computer-controls) where the DOM doesn't cooperate. | +| The site blocks the browser, shows a CAPTCHA, or the login is lost | Browser infrastructure: [stealth](/browsers/bot-detection/overview), [proxies](/proxies/overview), [authentication](/auth/overview) | +| The agent is slow between actions | Where the loop runs: see [how you drive the browser](/introduction/control) | + +## Where KERNEL fits in the agent stack + +| Area | What KERNEL provides | +| --- | --- | +| Working with your agent framework | [Integrations](/integrations/overview) for the frameworks and agents you already use, and guides for each [computer use model](/integrations/computer-use/overview). The [MCP server](/reference/mcp-server) exposes KERNEL as tools, [Agent Skills](/skills/overview) teach coding agents how to use it, and [cookbooks](/cookbooks) include working prompts for common browser tasks. | +| Browser execution | [Playwright execution](/browsers/playwright-execution), the [Browser REPL](/browsers/repl), and [computer controls](/browsers/computer-controls) all run against the same browser, so an agent can mix DOM and screen actions. [WebMCP](/browsers/webmcp) lets an agent call the structured tools a site exposes. The [code execution platform](/apps/develop) runs your agent co-located with its browser. | +| Access and authentication | [Stealth](/browsers/bot-detection/overview), [proxies](/proxies/overview), and [Web Bot Auth](/browsers/bot-detection/web-bot-auth) help the browser get through, and [Config Registry](/config-registry) recommends configurations that have worked on a site. [Profiles](/browsers/profiles), [vaults](/vaults/overview), [authentication](/auth/overview), and [payments](/browsers/payments) carry state and credentials into a session. | +| Observability | [Live view, replays, and telemetry](/introduction/observe) show what happened in a session. | +| Scale | Each plan has a set [concurrency limit and browser create rate](/browsers/concurrency-and-limits), and both go up when you [upgrade your plan](/info/pricing). [Browser pools](/browsers/pools) keep pre-configured browsers running, so acquiring one is instant and doesn't count against the create rate. | diff --git a/overview/features.mdx b/overview/features.mdx new file mode 100644 index 00000000..4073a436 --- /dev/null +++ b/overview/features.mdx @@ -0,0 +1,83 @@ +--- +title: "See All Features" +description: "Cloud browsers, and everything your agents need to stay unblocked, log in, pay, and scale on real websites" +mode: "wide" +--- + +KERNEL is browser infrastructure for AI agents. Its features cover five jobs: running browsers, accessing any website, carrying state, logins, and payments into a session, controlling the browser, and seeing what happened afterward. + +## Run browsers + + + + Headful by default, with headless and GPU-accelerated options. + + + Pre-configured browsers kept ready, so acquiring one skips start-up latency and the browser create rate limit. + + + Deploy your agent next to its browser and invoke it on demand or on a schedule. + + + +## Access any website + + + + Custom fingerprints and anti-bot detection defaults run on every browser, plus a managed CAPTCHA solver. + + + Datacenter, ISP, residential, mobile, or bring-your-own. + + + Give it a URL and get browser and proxy settings that have worked on that site. + + + +## Carry state, logins, and payments + + + + Persisted browser state (cookies, storage, logins, history, open tabs) that you can load into any browser. + + + Store credentials and fill them safely in a website form, with provider integrations like 1Password. + + + Fill logins from a vault, or let managed auth log in and attempt to reauthenticate eligible connections. + + + Let agents complete checkouts through wallet integrations like Link by Stripe, without card numbers passing through your app or model. + + + +## Control the browser VM + + + + Run Playwright code inside the browser's VM and get the result back in one call. + + + OS-level mouse, keyboard, and screenshots that match what computer use models emit. + + + Call the structured tools a website exposes instead of guessing which controls to click. + + + A persistent JavaScript runtime next to the browser, so an agent can build on its own helpers across calls. + + + +## See what happened + + + + Watch or take over a running session, and record any session as an MP4. + + + Structured events for navigation, network, CDP, captcha, and proxy activity. + + + A record of API requests across your organization, searchable and exportable on Start-Up and Enterprise. + + diff --git a/overview/why-kernel.mdx b/overview/why-kernel.mdx new file mode 100644 index 00000000..6134de15 --- /dev/null +++ b/overview/why-kernel.mdx @@ -0,0 +1,38 @@ +--- +title: "Why KERNEL?" +description: "Fast, secure browser infrastructure for agents, paired with the agent framework you already use" +--- + +KERNEL provides isolated cloud browsers for AI agents. It works underneath the agent framework you already use, with anti-detection, managed authentication, and tools for running browsers at scale. Your framework runs the loop and KERNEL runs the browser, so you can pick the best of each instead of settling for a browser bundled with a framework, or a framework bundled with a browser. See [integrations](/integrations/overview) for the frameworks and agents KERNEL works with, and [important concepts](/overview/concepts) for how the pieces fit. + +KERNEL is also built for speed, across the browser lifecycle and inside a running session. A browser is created in about 30ms at P50 and 105ms at P99, and your code can run in the browser's VM instead of across the network, so each action skips the round trip. On ComputeSDK's independent throughput benchmark, KERNEL led the providers tested on actions per second inside a running session. See [benchmarks](https://www.kernel.sh/benchmarks) for how KERNEL compares. + +## What sets KERNEL apart + +- **Headful by default.** Every browser has a real display and runs the full rendering pipeline. Sites that check for signs of a headless browser don't find them, computer use models see the page as it actually rendered, WebGL, canvas, and video work, and [live view](/browsers/live-view) and [replays](/browsers/replays) show the real session. Switch to [headless](/browsers/headless) per session when a job doesn't need it, or add [GPU acceleration](/browsers/gpu-acceleration) for graphics-heavy sites. +- **Each browser is its own VM.** Every browser runs isolated at the hypervisor, with its own kernel and filesystem, instead of sharing a host with other tenants. That's what makes a 30ms start and strong isolation possible at the same time, and it's why [file I/O](/browsers/file-io), [shell access](/browsers/ssh), and GPU access are safe to use inside a session. +- **Platform primitives, with managed services built on them.** [Profiles](/browsers/profiles) keep browser state between sessions, [vaults](/vaults/overview) hold credentials and payment items, and [browser pools](/browsers/pools) keep configured browsers ready. Managed services such as [managed auth](/auth/overview), [payments](/browsers/payments), [stealth](/browsers/bot-detection/overview), and the [code execution platform](/apps/develop) build on them. + +To put these to work, the how it works guides walk through each stage of a browser's life: [configure](/introduction/configure) it, [control](/introduction/control) it, [scale](/introduction/scale) it, [observe](/introduction/observe) it, and [manage](/introduction/manage) it across your team. + +## Why not just run Chrome yourself? + +You can. Running one Chrome locally is easy, and it's the right call while you're prototyping. The work starts when the automation has to run unattended, more than once, at more than one at a time. These are the problems you'd need to solve yourself: + +| What you hit | Running it yourself | On Kernel | +| --- | --- | --- | +| Start-up latency | Keep starts fast as you scale: image pulls, Chromium launch, and warm capacity to hide them | Browser creation in 30ms at P50 and 105ms at P99 ([performance](/browsers/performance)), or pre-configured browsers in a [browser pool](/browsers/pools) for instant acquisition | +| Isolation | Keep one session's page, files, and processes away from every other session on the same host | Each browser is a [microVM](/info/unikernels) with its own kernel and filesystem | +| Bot detection | You maintain the patches, the fingerprints, and a proxy contract | [Anti-detection](/browsers/bot-detection/overview) on every browser, plus a managed solver and [proxies](/proxies/overview), including bring-your-own | +| Sensitive credentials | Keep passwords and card details out of your agent's context and logs, and run the secret store that holds them | [Vaults](/vaults/overview) store sensitive information and fill it into the page without the values passing through your agent, [managed auth](/auth/overview) handles logins end to end, and [profiles](/browsers/profiles) persist state across sessions | +| Idle cost | Avoid paying for a running browser while you wait for end-user input | [Standby mode](/browsers/standby) suspends the browser and stops usage charges 5 seconds after the last client disconnects | +| Debugging a failure | Add your own logging and screen recording, then try to reproduce the failure | [Live view](/browsers/live-view), [replays](/browsers/replays), and [telemetry](/browsers/telemetry/overview) for the session that actually failed | +| Scaling | Provision more hosts, then build the autoscaling, image pipeline, and cleanup jobs around them | [Upgrade your plan](/info/pricing) to raise your [concurrency limit and browser create rate](/browsers/concurrency-and-limits), with custom limits on Enterprise. | + +## When KERNEL isn't the answer + +If the task can be done through an API or an MCP server, use that instead. It's faster and more reliable than driving a page. An API existing isn't enough on its own: it has to support the work you need, and many don't expose everything the site does. Use a browser when the task can only be done through the site itself, whether or not it needs a login: a portal with no API, data the API doesn't return, or a task where a computer use model has to see the page to take actions. + + + Every feature, each linking to its documentation. + diff --git a/proxies/custom.mdx b/proxies/custom.mdx index eeeec487..d5ceb320 100644 --- a/proxies/custom.mdx +++ b/proxies/custom.mdx @@ -107,7 +107,7 @@ func main() { ``` -## Configuration Parameters +## Configuration parameters - **`host`** (required) - Proxy server hostname or IP address - **`port`** (required) - Proxy server port (1-65535) diff --git a/proxies/datacenter.mdx b/proxies/datacenter.mdx index 46e623a3..27b54085 100644 --- a/proxies/datacenter.mdx +++ b/proxies/datacenter.mdx @@ -4,7 +4,7 @@ title: "Datacenter Proxies" Datacenter proxies use IP addresses assigned from datacenter servers to route your traffic and access locations around the world. With a shorter journey and simplified architecture, datacenter proxies are both the fastest and most cost-effective proxy option. -## IP Rotation Behavior +## IP rotation behavior Datacenter proxies use **rotating exit IPs** — a new exit IP is assigned per request, so different requests within the same browser session can exit through different IPs. @@ -86,7 +86,7 @@ func main() { ``` -## Configuration Parameters +## Configuration parameters - **`country`** (optional) - ISO 3166 country code (e.g., `US`, `GB`, `FR`) or `EU` for European Union exit nodes - **`bypass_hosts`** (optional) - Array of hostnames that bypass the proxy and connect directly (max 100 entries) diff --git a/proxies/isp.mdx b/proxies/isp.mdx index f9394c96..0d7be70b 100644 --- a/proxies/isp.mdx +++ b/proxies/isp.mdx @@ -4,7 +4,7 @@ title: "ISP Proxies" ISP (Internet Service Provider) proxies are hosted on datacenter infrastructure but use IP addresses assigned by real residential ISPs. Because the ASN belongs to a residential ISP, target sites see them as residential IPs — while the underlying datacenter hosting gives you the speed and stability you'd expect from a datacenter proxy. -## IP Rotation Behavior +## IP rotation behavior ISP proxies provide a **static exit IP that persists across sessions** — every tab, request, reconnection, and future browser session attached to this proxy exits through the same IP. The IP only changes in rare ISP-initiated replacement events. diff --git a/proxies/overview.mdx b/proxies/overview.mdx index 427db6a4..60502f0e 100644 --- a/proxies/overview.mdx +++ b/proxies/overview.mdx @@ -1,10 +1,11 @@ --- -title: "Overview" +title: "Proxies" +sidebarTitle: "Overview" --- Kernel proxies enable you to route browser traffic through different types of proxy servers, providing enhanced privacy, flexibility, and bot detection avoidance. Proxies can be created once and reused across multiple browser sessions. -## Proxy Types +## Proxy types Kernel supports five types of proxies: diff --git a/proxies/residential.mdx b/proxies/residential.mdx index f9132c3c..f695333e 100644 --- a/proxies/residential.mdx +++ b/proxies/residential.mdx @@ -96,7 +96,7 @@ func main() { ``` -## Configuration Parameters +## Configuration parameters - **`country`** - ISO 3166 country code. Must be provided when providing other targeting options. - **`state`** - Two-letter state code. Only supported for US. @@ -105,11 +105,11 @@ func main() { - **`asn`** - Autonomous System Number. Conflicts with city and state. - **`bypass_hosts`** (optional) - Array of hostnames that bypass the proxy and connect directly (max 100 entries) -## Advanced Targeting Examples +## Advanced targeting examples Kernel recommends using the least-specific targeting configuration that works for your use case. The more specific a configuration, the less available IPs there are, increasing the chance of a slow connection or no available connection (`no_peer` connection error). -### Target by City +### Target by city Route traffic through a specific city: @@ -163,7 +163,7 @@ _ = proxy If the city name is not matched, the API will return the best 10 city names from the state to help you find the correct city identifier. -### Target by State +### Target by state Route traffic through a specific state: diff --git a/reference/cli/managed-auth.mdx b/reference/cli/managed-auth.mdx index 01407e9a..dc230865 100644 --- a/reference/cli/managed-auth.mdx +++ b/reference/cli/managed-auth.mdx @@ -132,7 +132,7 @@ Delete a managed auth connection. | `--yes`, `-y` | Skip the confirmation prompt. | ## Credentials -Store login field values, TOTP secrets, and SSO settings that managed auth connections use to authenticate. See [Credentials](/auth/credentials) for concepts. +Store login field values, TOTP secrets, and SSO settings that managed auth connections use to authenticate. See [Credentials](/auth/configuration#credentials-and-auto-reauth) for concepts. ### `kernel credentials create` Create a new credential. diff --git a/security-vulnerability-reporting.mdx b/security-vulnerability-reporting.mdx index 13101b79..94a30a54 100644 --- a/security-vulnerability-reporting.mdx +++ b/security-vulnerability-reporting.mdx @@ -1,5 +1,6 @@ --- title: "Bug Bounty Program: Scope and Policy" +sidebarTitle: "Vulnerability Reporting" description: "Kernel's bug bounty scope, rewards, severity assessment, safe harbor, and rules of engagement" --- diff --git a/skills/overview.mdx b/skills/overview.mdx index d0f1df5e..5cabdfe2 100644 --- a/skills/overview.mdx +++ b/skills/overview.mdx @@ -1,15 +1,54 @@ --- -title: "Overview" +title: "Agent Skills" +sidebarTitle: "Agent Skills" +description: "Kernel skills that teach your coding agent how to use cloud browsers" +mode: "wide" --- -Kernel offers a suite of agent skills that can be used to debug your development workflows and give your browser agents runtime superpowers. +Skills give your coding agent Kernel know-how it keeps across sessions, so it doesn't have to re-read the docs every time. Install every Kernel skill into your project: -If you're building an agent that needs to access the internet, check out the [Kernel CLI skill](https://www.skills.sh/kernel/skills/kernel-cli). It gives your agent a direct path to Kernel's browser, proxy, profile, and authentication capabilities. It's a great starting point for users building custom agent harnesses. +```bash +npx skills add kernel/skills +``` -Especially useful skills: -- [Bot Detection](/skills/bot-detection) — teaches your agent how to profile a site's bot-detection setup and land on a browser configuration that gets through it. -- [Browser Profiles](/skills/profiles) — teaches your agent how to compare the actual contents of two Kernel browser profiles to identify state differences that could explain a reported issue. -- [Kernel Auth](/skills/kernel-auth) — teaches your agent best practices for using managed auth to log in to websites. -- [Create Site Skills](/skills/create-site-skills) — teaches your agent how to turn a verified browser workflow into a reusable skill for automating a specific site. +This works with any coding agent. To install KERNEL as your agent's native plugin instead, ask your agent to follow the install steps for itself in [kernel/skills](https://github.com/kernel/skills). -View Kernel's full list of available skills [here](https://skills.sh/kernel/skills). +## Most installed + + + + Best practices for using agent-browser with Kernel cloud browsers. + + + Manage browsers, pools, profiles, proxies, replays, extensions, managed auth, and app deployment from the CLI. + + + Build browser automation in TypeScript with playwright execution or CDP, profiles, and proxies. + + + Profile a site's bot-detection vendors and find a browser configuration that gets through. + + + Use managed auth to log in to websites that require an authenticated session. + + + Build and debug Python browser automation with the Kernel SDK. + + + +## More skills + + + + Turn a verified browser workflow into a reusable skill for automating a specific site. + + + Debug VM issues, network errors, Chrome crashes, page-load failures, and live view problems. + + + Best practices for using browser-use's browser-harness with Kernel over CDP. + + + Compare two profile snapshots to find state differences that explain an issue. + + diff --git a/snippets/calculator.jsx b/snippets/calculator.jsx index bbeed295..1e1ccbca 100644 --- a/snippets/calculator.jsx +++ b/snippets/calculator.jsx @@ -29,20 +29,21 @@ export const PricingCalculator = () => { const handleBrowserTypeChange = (type) => { hasInteracted.current = true; setBrowserType(type); - if (type === 'gpu' && plan !== 'startup') { + if (type === 'gpu' && plan !== 'startup' && plan !== 'enterprise') { setPlan('startup'); } }; const handlePlanChange = (newPlan) => { hasInteracted.current = true; - if (browserType === 'gpu' && newPlan !== 'startup') { + if (browserType === 'gpu' && newPlan !== 'startup' && newPlan !== 'enterprise') { return; } setPlan(newPlan); }; - var price = planPrices[plan]; + var isEnterprise = plan === 'enterprise'; + var price = isEnterprise ? 0 : planPrices[plan]; var multiplier = browserMultipliers[browserType]; var usageCost = usagePrices * multiplier * numSessions * avgSessionLength; @@ -89,9 +90,10 @@ export const PricingCalculator = () => {
@@ -110,16 +112,23 @@ export const PricingCalculator = () => {
${(usagePrices * multiplier).toFixed(8)}/second - {browserType === 'gpu' && (Startup tier required)} + {browserType === 'gpu' && (Start-Up or Enterprise plan required)}
- -
Base plan: ${planPrices[plan].toFixed(2)}
-
Usage: +${usageCost.toFixed(2)}
-
Free credits: -${includedUsageCredits.toFixed(2)}
-
Total cost: ${price.toFixed(2)}
- + {isEnterprise ? ( + +

Enterprise pricing is custom, with custom concurrency, rate limits, support, and compliance terms.

+

Contact the KERNEL team for a quote.

+ + ) : ( + +
Base plan: ${planPrices[plan].toFixed(2)}
+
Usage: +${usageCost.toFixed(2)}
+
Free credits: -${includedUsageCredits.toFixed(2)}
+
Total cost: ${price.toFixed(2)}
+ + )} ); }; diff --git a/start/quickstart.mdx b/start/quickstart.mdx new file mode 100644 index 00000000..4528ccea --- /dev/null +++ b/start/quickstart.mdx @@ -0,0 +1,197 @@ +--- +title: "Quickstart" +description: "Hand setup to your coding agent, or create your first cloud browser yourself" +mode: "wide" +--- + +import { CopyPromptButton } from '/snippets/copy-prompt-button.jsx'; + +Pick the way in that matches how you work. The first two are walked through on this page; the rest open their own guides. + + + + Copy one prompt into Cursor, Claude Code, or Codex and let it set up KERNEL. + + + Create and drive your first browser in TypeScript, Python, or Go. + + + Call KERNEL over HTTP from any language, starting with creating a browser. + + + Create, drive, and debug browsers from a terminal. + + + Give any MCP client, like Claude or Cursor, a cloud browser as a set of tools. + + + Teach your coding agent the KERNEL CLI, SDKs, and auth with one install. + + + Guides for the agent frameworks, models, and platforms you already use. + + + Clone an end-to-end recipe and adapt it to your task. + + + +## Path 1: hand it to your coding agent + +Copy this prompt into Claude Code, Codex, Cursor, or any agent that can run terminal commands. It installs the KERNEL CLI, signs you in, and opens a live view of a KERNEL browser that you or your agent can drive. From there, ask your agent to do a task on a site you care about. + +
+ +
+ + + +1. Checks for the KERNEL CLI and installs or upgrades it with Homebrew. +2. Checks whether you're signed in, and if not, runs `kernel login` and waits for you to finish signing in. +3. Creates a browser and opens its live view so you can watch it. + +It stops and asks you for help if any step fails. + + +| Surface | What it's for | +| --- | --- | +| [`kernel.sh/llms.txt`](https://www.kernel.sh/llms.txt) | Hand-written. What KERNEL is, when to use it, every machine endpoint. Start here. | +| [`kernel.sh/docs/llms.txt`](https://www.kernel.sh/docs/llms.txt) | Index of every docs page, for fetching the ones a task needs. | +| [`kernel.sh/docs/llms-full.txt`](https://www.kernel.sh/docs/llms-full.txt) | The whole docs corpus in one file, for agents with room for it. | +| [Agent Skills](/skills/overview) | KERNEL know-how installed into the agent, so it doesn't re-read docs every session. | +| [MCP server](/reference/mcp-server) | KERNEL's API as tools, for agents that call tools instead of writing code. | +| [OpenAPI 3.1](https://www.kernel.sh/openapi.json) | For generating a client or calling the REST API directly. | + + + +## Path 2: write it yourself with an SDK + + + +Create an API key in the [dashboard](https://dashboard.onkernel.com) and set it as `KERNEL_API_KEY`. Every SDK, the CLI, and the MCP server read it from the environment. + +```bash +export KERNEL_API_KEY= +``` + + + + +```bash TypeScript +npm install @onkernel/sdk +``` + +```bash Python +pip install kernel +``` + +```bash Go +go get github.com/kernel/kernel-go-sdk +``` + + + + +This creates a browser, runs Playwright code inside the browser's VM, returns the result, and cleans up. No local Chromium, no CDP connection to manage. + + +```typescript TypeScript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); + +const browser = await kernel.browsers.create({ timeout_seconds: 300 }); +console.log('live view:', browser.browser_live_view_url); + +try { + const { result } = await kernel.browsers.playwright.execute(browser.session_id, { + code: ` + await page.goto('https://news.ycombinator.com'); + return await page.$$eval('.titleline > a', (as) => as.slice(0, 5).map((a) => a.textContent)); + `, + }); + console.log(result); +} finally { + await kernel.browsers.deleteByID(browser.session_id); +} +``` + +```python Python +from kernel import Kernel + +kernel = Kernel() + +browser = kernel.browsers.create(timeout_seconds=300) +print("live view:", browser.browser_live_view_url) + +try: + response = kernel.browsers.playwright.execute( + browser.session_id, + code=""" + await page.goto('https://news.ycombinator.com'); + return await page.$$eval('.titleline > a', (as) => as.slice(0, 5).map((a) => a.textContent)); + """, + ) + print(response.result) +finally: + kernel.browsers.delete_by_id(browser.session_id) +``` + +```go Go +package main + +import ( + "context" + "fmt" + + "github.com/kernel/kernel-go-sdk" +) + +func main() { + ctx := context.Background() + client := kernel.NewClient() + + browser, err := client.Browsers.New(ctx, kernel.BrowserNewParams{ + TimeoutSeconds: kernel.Int(300), + }) + if err != nil { + panic(err) + } + defer client.Browsers.DeleteByID(ctx, browser.SessionID) + fmt.Println("live view:", browser.BrowserLiveViewURL) + + res, err := client.Browsers.Playwright.Execute(ctx, browser.SessionID, kernel.BrowserPlaywrightExecuteParams{ + Code: ` + await page.goto('https://news.ycombinator.com'); + return await page.$$eval('.titleline > a', (as) => as.slice(0, 5).map((a) => a.textContent)); + `, + }) + if err != nil { + panic(err) + } + fmt.Println(res.Result) +} +``` + + +Open `browser_live_view_url` while it runs and you'll watch the page load. + + + +## Next steps + +Two things determine the shape of everything after this: which control surface you use, and where your loop runs. [How you drive the browser](/introduction/control) covers both. + + + + Stealth and proxies to get past bot detection. + + + Fill credentials from a vault, or let managed auth log in. + + + Complete checkouts without exposing card data to your agent. + + + End-to-end recipes you can clone and run. + + diff --git a/style.css b/style.css index 9b8af45f..19f5385a 100644 --- a/style.css +++ b/style.css @@ -347,3 +347,8 @@ html.dark #navigation-items img[src*="/images/integration-icons/"] { html.dark .cookbook-tag { color: rgba(237, 238, 240, 0.7); } + +.copy-prompt-full button { + width: 100% !important; + max-width: 100% !important; +} diff --git a/vaults/overview.mdx b/vaults/overview.mdx index 68dab206..1071c22b 100644 --- a/vaults/overview.mdx +++ b/vaults/overview.mdx @@ -1,5 +1,6 @@ --- -title: "Overview" +title: "Vaults" +sidebarTitle: "Overview" description: "Group credentials and payment items, collect values, and control their use by attached browsers" --- @@ -27,6 +28,17 @@ navigation and submission, start with [Fill from Vault](/auth/fill-from-vault). see [wallet integrations](/integrations/wallets/overview). +## Choose where credentials come from + +a `credential` item can get its values from three places. all three end with the browser filling the login without your agent reading the values. + +| | [KERNEL-hosted collection](/vaults/credentials) | [an existing vault](/vaults/existing-credential-vault) | [1Password](/vaults/1password) | +| --- | --- | --- | --- | +| where the secret lives | encrypted in a KERNEL `credential` item | an encrypted copy in a KERNEL `credential` item | in the user's 1Password account | +| how it gets there | the user enters it in a KERNEL-hosted form, or your backend writes it | your backend copies it from the vault you already use and keeps it in sync | the user links their 1Password account once | +| who approves each use | your application or agent, when it calls `fill` | your application or agent, when it calls `fill` | the user, in the 1Password app | +| pick it when | you're collecting credentials from users for the first time | your credentials already live in another secrets manager | your users keep logins in a private 1Password vault | + ## How vaults work ### Sensitive values do not come back through the api @@ -72,7 +84,7 @@ availability. -### Inject values with KERNEL's fill api +### Inject values with KERNEL's fill API retrieve the item and require `fill` in `available_operations`. your controller authorizes the destination and supplies field names and selectors, not the stored values. KERNEL checks the browser attachment and item lifecycle, validates the target inputs, and writes values into the attached browser.