Restructure How it works: Configure, Control, Scale, Observe, Manage by andrewleesteele · Pull Request #671 · kernel/docs

andrewleesteele · 2026-10-05T19:57:54Z

Summary

First layer of the guides IA restructure (stack: #671 → #672 → #673 → #674). Adds the How it works section — Configure, Control, Scale, Observe, Manage — each with an overview page, and reorganizes the pages under it so readers see the features that matter before the knobs.

Configure

New overview covering browser creation, browser types (headful, headless, GPU), viewport, standby, and timeouts. The individual browser setting pages leave the sidebar and are linked from it.
Stealth, Proxies, Profiles, Vaults, Authentication, Payments, Config Registry.
Authentication nests the managed auth pages in their own group. Managed Auth Credentials is merged into Configuration (redirected), and the managed auth overview gets a connection options table.
The hCaptcha beta page folds into Stealth Mode (redirected). Vaults gets a credential-source comparison. Link by Stripe and AgentCard titles fixed.

Control

Overview leads with the control surface choice (now including WebMCP and the REPL) and where the loop runs. The "why" sections move into the computer controls and Playwright execution pages.
Sidebar: Playwright Execution, Computer Controls, WebMCP, Browser REPL, Process Execution, File I/O, Code Execution Platform. Curl and SSH are linked from the overview. Browser REPL gets its own tab under where the loop runs.
Code execution platform: secrets folds into Deploy and stopping into Invoke (both redirected); pages get task titles.

Scale

Overview leads with limits and performance, then the on-demand versus pool decision with on-demand as the default.
New Concurrency and Limits page holds every per-plan limit and the API rate limits; links to the old pricing anchors point at it.

Observe — Browser telemetry pages grouped under their own section.

Manage — New overview with a multi-tenant setups section. Network Access is retitled as the firewall allowlist. Projects headings move to sentence case.

Across the section, overview pages get specific titles (for example "Proxies Overview") and headings use sentence case.

Stack notes

Merge the stack in order. Until #673 merges, pages not yet moved stay in their existing sidebar groups, so every layer builds and has no broken links on its own.

Open PRs to reconcile when merging

Clarify when to use browser pools #641 (browser pool guidance): its Scale overview text is already included here; keep this version of introduction/scale.mdx and reapply its pools/create edits with the new limits anchors.
docs(auth): add Fill from Managed Auth how-to #622, Document custom WebMCP tools #629, Document browser egress allowlists #657, Document per-host proxy routes #661, Document browser location controls #602: add their new pages to the new groups (Authentication › Managed Auth, Control after WebMCP, Configure overview's settings list, Proxies, Configure overview).
Update Link payment docs for checkout-bound authorization #630, Document persistent proxies and plan inventory limits #651, Document restricted-destination routing beyond .gov #618: proxy and payments content edits; merge cleanly or rebase on the new page titles.

Testing

mint validate and mint broken-links pass on this branch.
Rendered locally to check the Configure, Control, Scale, Observe, and Manage overviews.

🤖 Generated with Claude Code

Note

Low Risk
Documentation-only IA, content moves, and redirects; no runtime or API behavior changes.

Overview
Reorganizes the Guides tab around a new How it works flow—Configure, Control, Scale, Observe, and Manage—each with an overview page (introduction/configure, control, scale, observe, manage) and regrouped sidebar pages so readers hit capabilities before deep settings.

Configure: Stealth (hCaptcha content moved into stealth, standalone page removed), proxies, profiles, vaults, authentication (managed auth nested; auth/credentials deleted and merged into auth/configuration with redirects), payments, and config registry. Overview pages get clearer titles/descriptions; vaults adds a credential-source comparison table.

Control: Overview reframes control surface vs where the loop runs; app platform docs consolidate—secrets into apps/deploy, stop into apps/invoke (old pages removed + redirects). Task-oriented titles on develop/deploy/invoke/logs/status.

Scale: New browsers/concurrency-and-limits centralizes concurrency, app invocation limits, rate limits (429/headers), and per-browser memory; links that pointed at pricing anchors now target this page.

Observe / Manage: Telemetry grouped under Observe; Manage overview covers projects, API keys, spending, audit logs, and firewall allowlist (info/network-access retitled). docs.json adds SEO indexing, redirects, and trims the old top-level create/control/observe/scale intro list from Overview.

Cross-doc link and changelog updates follow the moves (e.g. Foreman cookbook path, credential links → configuration anchor).

^{Reviewed by Cursor Bugbot for commit fcdf3c3. Bugbot is set up for automated code reviews on this repo. Configure here.}

mintlify · 2026-10-05T19:58:00Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
Kernel	🟢 Ready	View Preview	Oct 6, 2026, 10:04 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

cursor

Stale Bugbot comment from a previous run.

dprevoznik · 2026-10-05T21:51:40Z

-title: "Developing"
+title: "Develop an App"
+sidebarTitle: "Develop"
+description: "Build an app with actions that run next to KERNEL browsers"


Suggested change

description: "Build an app with actions that run next to KERNEL browsers"

description: "Build an app with actions that run co-located with KERNEL browsers"

dprevoznik · 2026-10-06T03:42:03Z

+
+| Resource | Headful | Headless |
+| --- | --- | --- |
+| Default memory | 8 GB | 1 GB |


consider mentioning support for up to 16 GB in headful.

dprevoznik

Left some comments!

dprevoznik · 2026-10-06T03:46:02Z

+</CodeGroup>
+
+- **[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.
+- **[Standby](/browsers/standby):** after 5 seconds with no CDP, WebDriver, live view, or computer controls activity, a browser goes into standby. It keeps its state and stops accruing usage cost until something reconnects.


i'd remove this here. not sure it belongs contextually.

dprevoznik · 2026-10-06T03:46:43Z

+
+## More browser settings
+
+Most agents never need these, but they're there when you do:


Suggested change

Most agents never need these, but they're there when you do:

Often agents don't require these, but they're there when you do:

dprevoznik · 2026-10-06T03:49:16Z

+| [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. |
+| [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. | JavaScript only, and state lives until the REPL resets. |


I'd actually lean on Browser Repl as the default at this time for on-vm control

"state lives until the REPL resets." i actually think this is a positive too of repl!

On second thought, We can leave playwrighht execution as the default for now, but worth likely overhauling to default to browser repl once the dust settles on the docs

dprevoznik · 2026-10-06T03:51:06Z

+
+| 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. |


another trade-off here is that each playwright execution api call is stateless (vs. browser repl which is stateful across cells)

dprevoznik · 2026-10-06T03:55:07Z

+    **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.
+  </Tab>
+  <Tab title="Playwright execution API">
+    Send code, not commands. Each call runs in the browser's VM against the live session, so state carries across calls and an agent can drive the page turn by turn — one tool call per step, structured data back.


"so state carries across calls" this is true for browser repl but not playwright execution api

i'd reco adding browser repl as a tab here too

dprevoznik · 2026-10-06T03:57:30Z

+
+If you're building your own agent, [Browser Loop](/browsers/browser-loop) packages these surfaces as tools for each model provider and runs every action against a KERNEL browser, so you don't write the translation layer yourself.

 ## Going deeper


i'd add browser repl in this list of additional reading options too

dprevoznik · 2026-10-06T04:01:21Z

@@ -0,0 +1,87 @@
+---
+title: "Browser Loop"


Consider removing from current PR and postpone inclusion till further internal discussion is done.

cursor

Cursor Bugbot has reviewed your changes using default effort and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 18ca8c3. Configure here.}

cursor · 2026-10-06T20:03:38Z

+
+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.


Configure copies region codes

Medium Severity

The new Configure overview inlines the shipped region codes us-east, eu-west, and ap-southeast instead of only linking to the canonical Regional Browsers page.

^{Triggered by learned rule: Regional browsers: latency not residency; canonical /browsers/regions}

^{Reviewed by Cursor Bugbot for commit 18ca8c3. Configure here.}

cursor · 2026-10-06T20:03:38Z

+| `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.


Limits page duplicates pricing

Medium Severity

The new Concurrency and Limits page restates the per-plan concurrency table, pool and standby notes, and rate-limit header behavior that still live on Pricing, so the two pages can drift.

^{Reviewed by Cursor Bugbot for commit 18ca8c3. Configure here.}

cursor · 2026-10-06T20:03:38Z

-    { "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" },


Missing credentials markdown redirect

Medium Severity

/auth/credentials.md has no redirect after the credentials page was merged, and the new secrets, stop, and hCaptcha redirects also omit their .md sources.

Additional Locations (1)

docs.json#L8-L11

^{Triggered by learned rule: Add redirects in docs.json when removing or moving pages}

^{Reviewed by Cursor Bugbot for commit 18ca8c3. Configure here.}

AnnaXWang

I really like this - can we double check that old links will automatically redirect to new links?

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

andrewleesteele · 2026-10-06T22:13:47Z

Yes, every link that works today will keep working!

andrewleesteele added this pull request to stack #675 October 5, 2026 19:58

mintlify Bot deployed to staging October 5, 2026 19:58 View deployment

andrewleesteele changed the title ~~hypeship/ia how it works~~ Restructure How it works: Configure, Control, Scale, Observe, Manage Oct 5, 2026

This was referenced Oct 5, 2026

Add Start building: quickstart, agent skills, integrations, cookbooks #672

Open

Add Partnering with KERNEL: pricing, billing, security and trust, enterprise #673

Open

Add Overview: introduction, features, concepts, why KERNEL #674

Open

dprevoznik marked this pull request as ready for review October 5, 2026 21:15

cursor Bot reviewed Oct 5, 2026

View reviewed changes

Comment thread introduction/configure.mdx

dprevoznik reviewed Oct 5, 2026

View reviewed changes

dprevoznik reviewed Oct 6, 2026

View reviewed changes

andrewleesteele force-pushed the hypeship/ia-how-it-works branch from 4647ff9 to 18ca8c3 Compare October 6, 2026 19:58

mintlify Bot deployed to staging October 6, 2026 19:59 View deployment

cursor Bot reviewed Oct 6, 2026

View reviewed changes

AnnaXWang reviewed Oct 6, 2026

View reviewed changes

Restructure How it works: Configure, Control, Scale, Observe, Manage

fcdf3c3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

andrewleesteele force-pushed the hypeship/ia-how-it-works branch from 18ca8c3 to fcdf3c3 Compare October 6, 2026 22:03

mintlify Bot deployed to staging October 6, 2026 22:04 View deployment

	description: "Build an app with actions that run next to KERNEL browsers"
	description: "Build an app with actions that run co-located with KERNEL browsers"


		## More browser settings

		Most agents never need these, but they're there when you do:

	Most agents never need these, but they're there when you do:
	Often agents don't require these, but they're there when you do:


		If you're building your own agent, [Browser Loop](/browsers/browser-loop) packages these surfaces as tools for each model provider and runs every action against a KERNEL browser, so you don't write the translation layer yourself.

		## Going deeper


		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.

Conversation

andrewleesteele commented Oct 5, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Stack notes

Open PRs to reconcile when merging

Testing

Uh oh!

mintlify Bot commented Oct 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dprevoznik left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Oct 6, 2026

Choose a reason for hiding this comment

Configure copies region codes

Uh oh!

cursor Bot Oct 6, 2026

Choose a reason for hiding this comment

Limits page duplicates pricing

Uh oh!

cursor Bot Oct 6, 2026

Choose a reason for hiding this comment

Missing credentials markdown redirect

Uh oh!

AnnaXWang left a comment

Choose a reason for hiding this comment

Uh oh!

andrewleesteele commented Oct 6, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

andrewleesteele commented Oct 5, 2026 •

edited by cursor Bot

Loading

mintlify Bot commented Oct 5, 2026 •

edited

Loading

cursor Bot left a comment •

edited

Loading