Add curll

Author: juecd

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.
+
+<CodeGroup>
+```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",
+);
+```
+</CodeGroup>
+
+## 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.
+
+<Info>
+  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.
+</Info>
+
+<CodeGroup>
+```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")
+```
+</CodeGroup>
+
+## 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.

docs.json

@@ -81,6 +81,7 @@
                   "browsers/termination",
                   "browsers/standby",
                   "browsers/headless",
+                  "browsers/curl",
                   "info/projects"
                 ]
               },