From 919e84ef18ee0237ca166a3ef7c835894ae46546 Mon Sep 17 00:00:00 2001 From: Catherine Jue Date: Wed, 29 Apr 2026 13:44:01 -0700 Subject: [PATCH 1/4] Add curll --- browsers/curl.mdx | 92 +++++++++++++++++++++++++++++++++++++++++++++++ docs.json | 1 + 2 files changed, 93 insertions(+) create mode 100644 browsers/curl.mdx diff --git a/browsers/curl.mdx b/browsers/curl.mdx new file mode 100644 index 0000000..b5cb2c7 --- /dev/null +++ b/browsers/curl.mdx @@ -0,0 +1,92 @@ +--- +title: "Curl" +description: "Send HTTP requests through a browser session's Chromium network stack so cookies, proxies, and TLS match real browsers" +--- + +Browser curl lets you run HTTP requests through Kernel browsers, automatically attaching the browser's cookie jar, transport fingerprint, [stealth and proxy settings](/bot-detection/overview), and other defaults that browsers send. This allows you to efficiently fetch resources from websites while getting the benefits of real browsers, including bot anti-detection and session cookie state. + +## Why this beats server-side `fetch()` + +When you call `fetch()` or `httpx`, you're on a different TLS stack, IP, cookie store, and header profile than the browsers your agents (or automations) are using. Browser curl runs requests directly through a Kernel browser's networking stack. + +### What curl requests inherit from Kernel browsers + +- **Cookies and storage policy** — Same cookie jar as the profile, including Chromium inclusion rules, `Set-Cookie` persistence, session cookies, encryption, `SameSite`, partitioning, and content settings. Response `Set-Cookie` headers update that same profile. +- **Transport fingerprint** — BoringSSL TLS, ALPN, HTTP/2, HTTP/3/QUIC where enabled, Alt-Svc, connection reuse, Happy Eyeballs, certificate verification, CT/HSTS policy. +- **Network configuration** — Proxy and PAC settings, DNS and Secure DNS, SSL and cert policy, cache, HTTP server properties, network quality signals. +- **Default client behavior** — Chromium user agent, `Accept-Language`, brotli/zstd support, and typical fetch metadata behavior. +- **Chromium request lifecycle** — Browser-managed redirects, decompression, HTTP authentication and client certificate eligibility, and cache behavior. + +## Streaming browser requests + +Streaming requests go through the browser's Chromium network stack, and the SDK mirrors platform-native HTTP ergonomics. + +You can stream or read the body incrementally, which avoids buffering the full payload in the browser for large responses. + + +```typescript Typescript/Javascript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); +const browser = await kernel.browsers.create({}); + +const response: Response = await kernel.browsers.fetch(browser.session_id, 'https://example.com', { + method: 'GET', +}); +``` + +```python Python +import httpx + +from kernel import Kernel + +const response: httpx.Response = client.browsers.request( + browser.session_id, + "GET", + "https://example.com", +); +``` + + +## Buffered browser curl + +Buffered browser curl calls the HTTP API and returns a single JSON envelope: `status`, `headers`, `body`, and `duration_ms`. Use it when the response is small enough to hold in memory and you want one structured object back—typical APIs, HTML snippets, and JSON payloads. + + + Buffered curl loads the **entire** response body into the browser process before it returns to you. Requesting a very large payload can exhaust memory and cause OOMs. For big downloads or unknown sizes, use [streaming browser requests](#streaming-browser-requests) instead. + + + +```typescript Typescript/Javascript +import Kernel from '@onkernel/sdk'; + +const kernel = new Kernel(); +const browser = await kernel.browsers.create({}); + +const buffered = await kernel.browsers.curl(browser.session_id, { + url: 'https://example.com', + method: 'GET', +}); +``` + +```python Python +from kernel import Kernel + +client = Kernel() +browser = client.browsers.create() + +buffered = client.browsers.curl(browser.session_id, url="https://example.com", method="GET") +``` + + +## Concurrency limits + +Browser curl concurrency is constrained by Chromium's internal networking limits: + +- **HTTP/1.x (direct)** — About 6 sockets per host group and up to 256 active sockets per pool. +- **Proxied chains** — On the order of tens of sockets per proxy chain (Chromium clamps configured values into a bounded range). +- **HTTP stream pool** — Similar per-group and per-pool behavior to HTTP/1.x direct connections. +- **HTTP/2** — Roughly 100 concurrent streams per session initially, updated from the server's `SETTINGS_MAX_CONCURRENT_STREAMS`, with an upper cap in Chromium (on the order of 256). +- **HTTP/3 / QUIC** — Stream creation can queue when peer or open-stream limits are hit. + +If you're issuing many parallel curls from one browser, you're sharing those pools with navigation, XHR, and other session traffic. Latency may vary, as Chromium may queue requests when it reaches its limits. diff --git a/docs.json b/docs.json index 884a131..335d212 100644 --- a/docs.json +++ b/docs.json @@ -81,6 +81,7 @@ "browsers/termination", "browsers/standby", "browsers/headless", + "browsers/curl", "info/projects" ] }, From a0df4d4ecd43cf0b866c7371ebec3ad3184e5135 Mon Sep 17 00:00:00 2001 From: Catherine Jue Date: Wed, 29 Apr 2026 13:49:34 -0700 Subject: [PATCH 2/4] Update --- browsers/curl.mdx | 19 ++++++++++++------- docs.json | 2 +- 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/browsers/curl.mdx b/browsers/curl.mdx index b5cb2c7..c1cb7c4 100644 --- a/browsers/curl.mdx +++ b/browsers/curl.mdx @@ -1,6 +1,6 @@ --- title: "Curl" -description: "Send HTTP requests through a browser session's Chromium network stack so cookies, proxies, and TLS match real browsers" +description: "Send HTTP requests through Kernel browsers" --- Browser curl lets you run HTTP requests through Kernel browsers, automatically attaching the browser's cookie jar, transport fingerprint, [stealth and proxy settings](/bot-detection/overview), and other defaults that browsers send. This allows you to efficiently fetch resources from websites while getting the benefits of real browsers, including bot anti-detection and session cookie state. @@ -28,11 +28,13 @@ You can stream or read the body incrementally, which avoids buffering the full p import Kernel from '@onkernel/sdk'; const kernel = new Kernel(); + const browser = await kernel.browsers.create({}); const response: Response = await kernel.browsers.fetch(browser.session_id, 'https://example.com', { - method: 'GET', +method: 'GET', }); +console.log('body', await response.text()); ``` ```python Python @@ -40,11 +42,12 @@ import httpx from kernel import Kernel -const response: httpx.Response = client.browsers.request( - browser.session_id, - "GET", - "https://example.com", -); +client = Kernel() + +browser = client.browsers.create() + +response: httpx.Response = client.browsers.request(browser.session_id, "GET", "https://example.com") +print("status", response.status_code) ``` @@ -67,6 +70,7 @@ const buffered = await kernel.browsers.curl(browser.session_id, { url: 'https://example.com', method: 'GET', }); +console.log('body', buffered.body); ``` ```python Python @@ -76,6 +80,7 @@ client = Kernel() browser = client.browsers.create() buffered = client.browsers.curl(browser.session_id, url="https://example.com", method="GET") +print("body", buffered.body) ``` diff --git a/docs.json b/docs.json index 335d212..de25a87 100644 --- a/docs.json +++ b/docs.json @@ -81,7 +81,6 @@ "browsers/termination", "browsers/standby", "browsers/headless", - "browsers/curl", "info/projects" ] }, @@ -109,6 +108,7 @@ ] }, "browsers/file-io", + "browsers/curl", "browsers/ssh", "browsers/computer-controls", "browsers/playwright-execution" From 3971e6a509595713929d523698d63d94e3007874 Mon Sep 17 00:00:00 2001 From: Catherine Jue Date: Thu, 30 Apr 2026 10:21:00 -0700 Subject: [PATCH 3/4] broken link --- browsers/curl.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browsers/curl.mdx b/browsers/curl.mdx index c1cb7c4..99908be 100644 --- a/browsers/curl.mdx +++ b/browsers/curl.mdx @@ -3,7 +3,7 @@ title: "Curl" description: "Send HTTP requests through Kernel browsers" --- -Browser curl lets you run HTTP requests through Kernel browsers, automatically attaching the browser's cookie jar, transport fingerprint, [stealth and proxy settings](/bot-detection/overview), and other defaults that browsers send. This allows you to efficiently fetch resources from websites while getting the benefits of real browsers, including bot anti-detection and session cookie state. +Browser curl lets you run HTTP requests through Kernel browsers, automatically attaching the browser's cookie jar, transport fingerprint, [stealth and proxy settings](/browsers/bot-detection/overview), and other defaults that browsers send. This allows you to efficiently fetch resources from websites while getting the benefits of real browsers, including bot anti-detection and session cookie state. ## Why this beats server-side `fetch()` From 74f05c09db23d5d1f9d04feb0339190cec007c80 Mon Sep 17 00:00:00 2001 From: Catherine Jue Date: Thu, 30 Apr 2026 12:55:15 -0700 Subject: [PATCH 4/4] Address comments --- browsers/curl.mdx | 5 ++--- skills/overview.mdx | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/browsers/curl.mdx b/browsers/curl.mdx index 99908be..bb42a03 100644 --- a/browsers/curl.mdx +++ b/browsers/curl.mdx @@ -5,14 +5,14 @@ description: "Send HTTP requests through Kernel browsers" Browser curl lets you run HTTP requests through Kernel browsers, automatically attaching the browser's cookie jar, transport fingerprint, [stealth and proxy settings](/browsers/bot-detection/overview), and other defaults that browsers send. This allows you to efficiently fetch resources from websites while getting the benefits of real browsers, including bot anti-detection and session cookie state. -## Why this beats server-side `fetch()` +## Why use browser curl instead of `fetch()` When you call `fetch()` or `httpx`, you're on a different TLS stack, IP, cookie store, and header profile than the browsers your agents (or automations) are using. Browser curl runs requests directly through a Kernel browser's networking stack. ### What curl requests inherit from Kernel browsers - **Cookies and storage policy** — Same cookie jar as the profile, including Chromium inclusion rules, `Set-Cookie` persistence, session cookies, encryption, `SameSite`, partitioning, and content settings. Response `Set-Cookie` headers update that same profile. -- **Transport fingerprint** — BoringSSL TLS, ALPN, HTTP/2, HTTP/3/QUIC where enabled, Alt-Svc, connection reuse, Happy Eyeballs, certificate verification, CT/HSTS policy. +- **Transport fingerprint** — BoringSSL TLS, ALPN, HTTP/2, Alt-Svc, connection reuse, Happy Eyeballs, certificate verification, CT/HSTS policy. - **Network configuration** — Proxy and PAC settings, DNS and Secure DNS, SSL and cert policy, cache, HTTP server properties, network quality signals. - **Default client behavior** — Chromium user agent, `Accept-Language`, brotli/zstd support, and typical fetch metadata behavior. - **Chromium request lifecycle** — Browser-managed redirects, decompression, HTTP authentication and client certificate eligibility, and cache behavior. @@ -92,6 +92,5 @@ Browser curl concurrency is constrained by Chromium's internal networking limits - **Proxied chains** — On the order of tens of sockets per proxy chain (Chromium clamps configured values into a bounded range). - **HTTP stream pool** — Similar per-group and per-pool behavior to HTTP/1.x direct connections. - **HTTP/2** — Roughly 100 concurrent streams per session initially, updated from the server's `SETTINGS_MAX_CONCURRENT_STREAMS`, with an upper cap in Chromium (on the order of 256). -- **HTTP/3 / QUIC** — Stream creation can queue when peer or open-stream limits are hit. If you're issuing many parallel curls from one browser, you're sharing those pools with navigation, XHR, and other session traffic. Latency may vary, as Chromium may queue requests when it reaches its limits. diff --git a/skills/overview.mdx b/skills/overview.mdx index 874e033..be6dcc9 100644 --- a/skills/overview.mdx +++ b/skills/overview.mdx @@ -5,7 +5,7 @@ title: "Overview" Kernel offers a suite of agent skills that can be used to debug your development workflows and give your browser agents runtime superpowers. Especially useful skills: -- [Bot Detection Profiler](/skills/bot-detection) +- [Bot Detection](/skills/bot-detection) - [Browser Profiles](/skills/profiles) View Kernel's full list of available skills [here](https://skills.sh/kernel/skills). \ No newline at end of file