Kuri Server

kuri — HTTP API Browser Automation Server

kuri is a CDP automation server. It launches Chrome, connects via WebSocket, and exposes an HTTP API for browser control. Zero Node.js, single binary.

Starting the server

# Default — launches headless Chrome, listens on :8080
./zig-out/bin/kuri

# Visible Chrome (for debugging)
HEADLESS=false ./zig-out/bin/kuri

# With residential proxy (for bot-protected sites)
KURI_PROXY=socks5://user:pass@proxy:1080 ./zig-out/bin/kuri

# Connect to existing Chrome
CDP_URL=ws://127.0.0.1:9222/devtools/browser/... ./zig-out/bin/kuri

Core workflow

Prefer the session-first loop: tab/new → page/info → snapshot → act → repeat

BASE=http://127.0.0.1:8080
SESSION=agent-demo

# 1. Create or switch into a session-scoped tab
curl -s -H "X-Kuri-Session: $SESSION" \
  "$BASE/tab/new?url=https%3A%2F%2Fexample.com"

# 2. Read live page info
curl -s -H "X-Kuri-Session: $SESSION" "$BASE/page/info"
# → {"tab_id":"ABC123","url":"https://example.com/","title":"Example Domain",...}

# 3. Snapshot (a11y tree with element refs)
curl -s -H "X-Kuri-Session: $SESSION" "$BASE/snapshot?filter=interactive&format=compact"
# → [{"ref":"e0","role":"heading","name":"Example Domain"},
#    {"ref":"e1","role":"link","name":"More information..."}]

# 4. Interact via refs
curl -s -H "X-Kuri-Session: $SESSION" "$BASE/action?ref=e1&action=click"
curl -s -H "X-Kuri-Session: $SESSION" "$BASE/action?ref=e2&action=fill&value=hello"

# 5. Read results
curl -s -H "X-Kuri-Session: $SESSION" "$BASE/page/info"
curl -s -H "X-Kuri-Session: $SESSION" "$BASE/snapshot?filter=interactive&format=compact"

If you already know a tab id, set it directly with:

curl -s -H "X-Kuri-Session: $SESSION" "$BASE/tab/current?tab_id=ABC123"

Choosing the right Kuri browser path

Use the main kuri server for production browser automation. It drives Chrome/CDP and exposes HTTP sessions, page info, snapshots, actions, HAR, cookies, and screenshots.

Use the separate kuri-browser/ workspace only for the experimental Zig-native browser runtime. It is not wired into the root build and cannot replace headless Chrome yet.

cd kuri-browser
zig build run -- render https://news.ycombinator.com --selector ".titleline a" --dump text
zig build run -- render https://todomvc.com/examples/react/dist/ --js --wait-eval "document.querySelectorAll('.todo-list li').length >= 1"
zig build run -- bench --offline
zig build run -- parity --offline
zig build run -- serve-cdp --port 9333

serve-cdp exposes Chrome-style HTTP discovery plus a minimal WebSocket JSON-RPC router. It can answer basic Browser/Target/Page/Runtime/DOM methods, and Runtime.evaluate returns V8-shaped CDP remote objects backed by QuickJS. This is useful for protocol smoke tests, but it is not broad Playwright/Puppeteer compatibility and cannot replace Chrome yet.

For screenshots, kuri-browser currently delegates to the main Kuri/CDP renderer:

# terminal 1, repo root
zig build
./zig-out/bin/kuri

# terminal 2
cd kuri-browser
zig build run -- screenshot https://example.com --out example.jpg --compress --kuri-base http://127.0.0.1:8080

--compress captures a PNG baseline and JPEG candidate, writes the smaller file, and reports byte savings. Current local measurement on https://example.com: 20,523 bytes PNG to 18,183 bytes JPEG quality 50, saving 2,340 bytes or 11%.

Key endpoints

Design limit — paused CDP events need a live command to make progress. Chrome delivers most async CDP events (screencast frames, exposed-binding calls, network records, tracing completion, download signals, dialog opens) only while some command is in flight on the same CDP socket; nothing else reads it. Endpoints that consume a ring/collector (/screencast/stop, /expose/calls, /network?mode=list, /response/body?url=..., /trace/stop, /wait/download, /dialog/auto) explicitly drain the socket (drainWsEvents/waitForEvent) before reading, so a normal call sequence self-heals on the very next request. A caller that goes fully idle between calls won't see new events arrive on their own — this is a documented limitation, not a bug, and does not need (or want) a background thread to paper over it.

Navigation & page control

Reading the page

Interacting

Downloads

Inspector

Debugging (console & errors)

Both return the raw CDP wrapper — unwrap with jq -r '.result.result.value' | jq '.'. A collector script is injected on every navigation, so console output and errors are captured from page load. Caveat: messages emitted on a brand-new tab's first document, before the collector installs, are not captured — navigate or reload once and every subsequent load captures fully.

Network & cookies

Network interception (Fetch domain)

All six honor X-Kuri-Session in place of tab_id.

Two different matching engines — don't confuse them. /intercept/start's patterns param maps onto real CDP Fetch.enable glob patterns (Chrome's own urlPattern syntax, e.g. api.*.com matches as a glob). /intercept/rules's url_pattern does not — rules match by plain substring containment against the request URL, in the order added; "*" is special-cased only as a whole-pattern catch-all, not as a mid-string wildcard ("api.*.com" is matched literally, asterisk included). Fetch.authRequired (real 401/407 auth challenges) is not answered anywhere in this codebase yet — only request pausing is handled.

GET /intercept/requests?tab_id=X branches on whether interception is currently active for the tab (tracked precisely by /intercept/start//intercept/stop, not inferred from request count). Active: {"source":"intercepted","requests":[{"request_id","url","method","resource_type","action":"continue|abort|fulfill","status","timestamp"}],"count":N} — the real ring of paused requests; an empty array is a valid answer if nothing has paused yet. Inactive: falls back to the pre-existing Resource Timing API Runtime.evaluate call, byte-for-byte unchanged, with "source":"resource_timing" spliced into the raw CDP envelope so old code parsing .result.result.value keeps working while new code can check .source.

JS bindings (window.<name>() → host)

Dialogs

Response: {"ok":true,"mode":"accept|dismiss|off"}. Honors X-Kuri-Session. mode=accept/mode=dismiss now also arms the CDP-level auto-responder in the client itself, so Page.javascriptDialogOpening is actually answered between HTTP calls — previously this endpoint only touched page-local JS globals and left native dialogs outside those calls to hang the tab.

Bot protection

Screencast, video & tracing

React introspection

All four degrade identically to {"react":false} when no React is on the page — never an error. Fiber/suspense ids are single-slot per tab and last-call-wins (fibers aren't stable across re-renders), so an id from /react/tree or /react/suspense is only valid until the next call to either on that tab. No iframe/OOPIF walking (same v1 boundary as /frame//mainframe). Pre-Fiber React (≤15) is indistinguishable from "no React."

HAR replay workflow (bypass browser for API calls)

When browser interaction is flaky or you want to call APIs directly:

# 1. Start recording
curl -s "$BASE/har/start?tab_id=ABC123"

# 2. Navigate and let the page load
curl -s "$BASE/navigate?tab_id=ABC123&url=https://target.com&bot_detect=false"
sleep 8

# 3. Get API map with code snippets
curl -s "$BASE/har/replay?tab_id=ABC123&filter=api&format=curl"
# → {"api_calls":[
#     {"method":"POST","url":"https://target.com/api/v4/data",
#      "request_headers":"{\"Cookie\":\"...\",\"X-CSRFToken\":\"...\"}",
#      "post_data":"{\"query\":\"...\"}",
#      "curl":"curl -X POST 'https://target.com/api/v4/data'"}
#   ]}

# 4. Grab cookies for direct API calls
curl -s "$BASE/cookies?tab_id=ABC123"

# 5. Call APIs directly with captured cookies + headers
curl -s 'https://target.com/api/v4/data' \
  -H 'Cookie: session=abc; csrf=xyz' \
  -H 'X-CSRFToken: xyz'

Endpoints that require an explicit tab_id

Every endpoint that operates on exactly one tab resolves it from X-Kuri-Session (or an explicit tab_id/session query param) the same way /console does — a full audit of the route table found 113 direct requireEffectiveTabId call sites plus 9 more via the inline session/tab_id resolver already used by /console, /errors, and all /intercept/*. A handful of routes are intentionally exempt because "the current tab for this session" isn't the right concept for them:

Everything not in this list honors X-Kuri-Session.

Tips for agents

1. Prefer session headers — set X-Kuri-Session and let the server remember the current tab. This covers nearly every tab_id=X endpoint above — cookies, storage, HAR, emulation, keyboard input, tracing, network interception, downloads, screencast/video, exposed bindings, React introspection, and dialog auto-response all resolve the session the same way /console//errors do. See "Endpoints that require an explicit tab_id" above for the intentional exceptions.
2. Use /page/info between steps — it is the cheapest live state check for URL/title/ready state.
3. Use compact interactive snapshots — filter=interactive&format=compact gives refs like e0, e1 plus useful state such as checked=false, disabled, or expanded=false at lower token cost.
4. Bot detection is automatic — if navigate returns {"blocked":true}, read the fallback.suggestions.
5. HAR for API discovery — start HAR before navigating, then use /har/replay?filter=api to find the site's API endpoints.
6. Cookies transfer — use /cookies to get browser session cookies, then make direct curl calls.
7. Refs persist per snapshot only — take a new snapshot after any navigation or meaningful DOM change.
8. Native browser experiment is separate — kuri-browser is useful for parity work and benchmarks. Its serve-cdp router is minimal, screenshots still use the Kuri/CDP fallback, and native layout/paint is not implemented.
9. Idle tabs don't self-update — screencast frames, exposed-binding calls, network records, and trace/download completion only get pulled off the CDP socket while some command is in flight. If you go fully idle between calls, make one more call (even the same read) to let the server catch up; see the design-limit note under "Key endpoints" above.