# ⚡ Hyperbolic Gateway ## The Local Web Browser for Your AI Agents > _"I'll hack the Gibson"_ > — **Dade Murphy (AKA Crash Override)**, Circa 1995

version tools resources license platform

## 🧭 Index - **About** — [What it is](#sec-what-it-is) · [A punk-ethos alternative to browser clouds](#sec-a-punk-ethos-diy-alternative-to-browser-use-play) - **The deck** — [Theme & Cyberdeck UI](#sec-theme-cyberdeck-interface) · [Ghost cursor telemetry](#sec-ghost-cursor-telemetry-engine) · [Focus-independent input](#sec-focus-independent-input-background-rendering) · [Multi-tab browsing](#sec-hardware-accelerated-multi-tab-browsing) - **Reading the web** — [Orthogonal primitive layer](#sec-orthogonal-primitive-layer) · [Construct harvester](#sec-token-efficient-construct-harvester) · [Set-of-Marks](#sec-set-of-marks-som-visual-grounding) - **Driving the web** — [Shield-breaker](#sec-autonomous-shield-breaker-cookie-gdpr-destroyer) · [Form filler](#sec-single-turn-batch-form-filler) · [Human-in-the-loop](#sec-human-in-the-loop-hil-intervention-protocol) - **Memory & data** — [Cortex](#sec-lancedb-persistent-cortex-semantic-recall) · [Downloads](#sec-download-manager-cortex-harvester) · [Session vault](#sec-session-cookie-jar-vault) · [Script vault](#sec-script-vault-lancedb-semantic-macro-engine) · [Timelapse recorder](#sec-timelapse-recorder) - **Inspection** — [Network & API streams](#sec-live-network-api-stream-interceptor) · [WebSocket & SSE](#sec-real-time-websocket-sse-interceptor) - **Operating it** — [System tray](#sec-system-tray-background-minimization-out-of-the-w) · [MCP tools (63 advertised)](#sec-standardized-semantic-mcp-tools-63-advertised) · [REST wrappers](#sec-rest-wrappers-hb-rest) - **Building on it** — [Architecture lowdown](./docs/CODEBASE.md) · [Codebase & docs](#sec-codebase-directory-structure-documentation) · [Quickstart](#sec-quickstart) · [Testing](#sec-testing) · [OKF knowledge](#sec-documentation-knowledge-okf) - **Optional decision layer** — [`decide` / `drive` design notes](./docs/DECISION_MODELS.md) · [Control layer: targeting, consent, human takeover](./docs/CONTROL_LAYER.md) · [Shadow DOM & iframes: what Hyperbolic Gateway can see and click](./docs/SHADOW_DOM_AND_FRAMES.md) · [Shadow Walk: sealed-content plan](./docs/SHADOW_WALK.md) · [Field notes from dogfooding](./docs/FIELD_NOTES_2026-10-20_SIGNUP.md) · [Changelog](./CHANGELOG.md) - **Release notes** — [What shipped](#sec-release-notes) · [All releases](./CHANGELOG.md) - **Lore** — [Neuromancer inspiration](#sec-neuromancer-inspiration-cyberpunk-canon) --- ## 🕶️ What it is **Hyperbolic Gateway is a visible, stateful web browser that any MCP agent can drive.** Most agent browsers are a library you integrate, or a cloud you rent. **Hyperbolic Gateway** is a desktop application you own: a real Chromium window on your machine, controlled over the Model Context Protocol. Your agent runs where you already run it — local or remote — and Hyperbolic Gateway supplies the browser, the input, and the memory. - **A real browser, not a simulation.** Visible Chromium with hardware acceleration, persistent cookies, real tabs, downloads, and a human-sized viewport. No headless fingerprint. - **Structured first, pixels when needed.** `observe` returns a compact, addressable view of the page (markdown, text, accessibility tree, or Set-of-Marks). `take_screenshot` is there when layout matters. - **Input that looks human.** Clicks and keys travel over the Chrome DevTools Protocol with Bézier paths and Gaussian typing cadence — and they land even when another application owns the foreground. - **State that survives.** LanceDB memory, bookmark and session vaults, download harvesting and a script vault mean the next session starts where the last one stopped. - **Self-hosted by construction.** `stdio` MCP plus a localhost bridge. No account, no dashboard, and no telemetry leaving the machine. ![Hyperbolic Gateway driving a real Chromium window](docs/assets/demo.webp) [Open the MP4](docs/assets/demo.mp4) if your browser does not animate WebP. > [!WARNING] > **EXPERIMENTAL PROTOTYPE**: Hyperbolic Gateway is currently under active, experimental development. Tool contracts, telemetry tuning, and database schemas may evolve rapidly. Built for developers experimenting with multimodal local AI agents. > [!IMPORTANT] > **RESEARCH PURPOSES ONLY**: This software is provided strictly for educational, testing, and local AI agent research purposes. It is **not intended for malicious use**, automated credential stuffing, unauthorized exploitation, or violating third-party websites' Terms of Service. Users are responsible for complying with all applicable laws and terms. **Installers:** grab them from [Releases](https://github.com/hyperbolictonic/hyperbolic-gateway/releases) — Windows `Setup`/`Portable`/`zip`, macOS `dmg`/`zip` (x64 + arm64), Linux `AppImage`/`deb`/`tar.gz`. macOS is **unsigned** for now: right-click → **Open** (or `xattr -dr com.apple.quarantine "/Applications/Hyperbolic Gateway.app"`). Built by GitHub Actions; see [`docs/BUILDING.md`](./docs/BUILDING.md). ## 🤘 A Punk-Ethos, DIY Alternative to browser-use, Playwright Agents & Hosted Browser Clouds Most "AI browser" tooling today is a **library you integrate, or a cloud you rent**. [`browser-use`](https://github.com/browser-use/browser-use) is a popular MIT-licensed Python framework that drives Playwright _with its own agent loop_ (plus an optional hosted cloud); Playwright / Puppeteer / Selenium are general-purpose drivers where **you** write the loop; and managed browser clouds run a remote Chromium and bill per session. They're good tools — this isn't a rivalry, it's a different **shape**. **Hyperbolic Gateway is the other road:** a single, self-hosted **desktop app you own** (Electron, no account, no dashboard). It runs a **real, visible Chromium** on your own machine and speaks **MCP** over `stdio` (+ a localhost bridge), so it drops into whatever agent runner and whichever model you already use — **local or remote, with no cloud account, no API key, no seat pricing, and no telemetry leaving your box.** That's the punk ethos: **one operator, one machine, a tool you can read, fork and keep.** Built by one person, not a company. No VC, no roadmap-by-committee, no dashboard. ### How it differs, honestly | | `browser-use` (Python / Playwright) | Playwright · Puppeteer agents | Hosted browser clouds | **Hyperbolic Gateway** | | :---------------- | :----------------------------------- | :---------------------------- | :---------------------- | :------------------------------------------------------------------------------------------ | | **Shape** | Library **with its own agent loop** | Driver — you write the loop | Managed remote browser | **MCP server** any MCP client can call | | **Browser** | Playwright Chromium (often headless) | Playwright / Puppeteer | Remote Chromium | **Visible Chromium** (`headless: false`) in an Electron chassis | | **Where it runs** | Your machine, or their cloud | Your machine / your CI | Their datacentre | **Your machine, always** — local-first | | **Model** | Bring your own (usually a cloud LLM) | Bring your own | Bring your own | **Bring your own — local or remote** | | **Input** | Playwright-driven events | Playwright-driven events | CDP over the wire | **Focus-independent CDP input** + Bézier ghost cursor + Gaussian typing (`isTrusted: true`) | | **Memory** | Framework-level, BYO store | none | Their store | **Local LanceDB "Cortex"** — semantic recall of everything it harvests | | **Cost** | MIT + your LLM (+ optional cloud) | Free + your LLM | **Per-session billing** | **MIT. No cloud, no metering, no telemetry.** | ### What that buys you in practice - **Self-hosted and local-first.** The browser, the memory, the logs and the model all stay on the box. - **Built for a machine you're _also_ using.** Input goes over CDP and is **focus-independent** — clicks and typing land while your editor owns the foreground — and occluded windows keep hydrating and scrolling, so long harvests keep running behind your other apps. - **Tier-graded tool surface, not a token bonfire.** Reading is `observe(as:"markdown")` with inline `[#id]` marks (no screenshot tax); interaction is one `act`; `[TIER 1/2/3]` prefixes plus a `tools/recommended` resource tell the agent what to prefer. - **Honest about its limits.** Detached reads are gated, `evaluate_javascript` is _"use deliberately"_ rather than banned, and failures are machine-coded (`STALE_REF`, `TIMEOUT`, `NO_TARGET`, `BAD_REQUEST`, `NOT_SUPPORTED`) instead of vibes. - **No framework lock-in.** Because the interface is MCP, your runner stays yours: swap the agent, swap the model, keep the tool. ### New here? Plain-English FAQ **What is this, in one sentence?** A web browser that an AI can drive for you: it opens real pages, reads them, clicks, types, fills in forms, and remembers what it found. **Is it a browser I use myself?** It's a real browser window. You can watch it, and you can take over at any time — most people just let their AI do the driving. **Do I need to be a programmer?** To _use_ it with an AI assistant you already have: no — you paste one line of configuration into that assistant. To change how it behaves internally: yes, it's a code project. **What's an "MCP server", in plain terms?** MCP is a standard plug shape for AI tools. If your AI app accepts MCP plugins, it can use this one. Claude Desktop, Cursor and several other apps speak it. **Which AI can drive it?** Any assistant that supports MCP — a cloud service, or a model running on your own computer. You choose, and you aren't locked to one provider. **Do I need to pay for anything?** No subscription and no account. The software is free and open source. The only cost is whatever you already pay for your AI, if anything. **Where does my data go?** Nowhere. The pages it reads, the notes it keeps and the logs all stay on your computer. There's no company server in the middle and no usage tracking. **Could a website tell it's a bot?** It's built to be hard to spot: a normal visible browser, mouse movement and typing that look human, and it clears cookie banners politely. Nothing is unbeatable, but it isn't the obvious "automated script" that gets blocked. **What happens at a CAPTCHA?** It doesn't solve them. It asks you to step in (it can send a notification and bring the window forward), then continues once you're done. **Does it run headless on a server?** Not really, and that's on purpose. It runs a visible browser on a normal desktop, which is exactly why it looks human. For large-scale server-side scraping, a different tool fits better. **Is using it allowed?** It's for personal research and testing. You still have to follow each website's rules and the law — running it yourself doesn't change that. Don't use it to break into accounts or ignore terms of service. **What do I need to run it?** A normal Windows desktop (that's the tested target). If your computer can run a browser and an AI assistant, it can run this. **Is it finished?** No. It's an experimental project by one developer — expect rough edges and things that change. ### FAQ for developers — browsers, memory, and the tricky bits **Is there a self-hosted, open-source alternative to browser-use?** Yes — MIT-licensed and entirely local. But note the shape: this is a _tool surface_, not an agent framework. If you want a Python framework that owns the loop, `browser-use` is the right tool; if you want a self-hosted browser that _your own_ agent drives, this is it. **Can I use it with Claude Desktop, Cursor, or a local LLM?** Yes. It's an MCP server, so any MCP client works - point your client at `bin/mcp-server.cjs` and the `hb-browser` tool namespace appears (legacy `kuang` alias still works). **Does it need a cloud account, API key, or per-session billing?** No. There is no cloud tier. The only network calls are the ones your agent makes to the pages it visits (plus, optionally, a search engine via `search_web`). **Is it headless?** Deliberately the opposite. It runs a **visible** Chromium so a human can watch, take over at a CAPTCHA, and so the session stays an honest, real browser. Headless-at-scale scraping is a different job; this is a single operator's console. **Will Cloudflare block it like Puppeteer / Playwright?** It's built for exactly that fight: real CDP input with `isTrusted: true`, cubic Bézier pointer kinematics, Gaussian typing cadence, a genuine cookie jar, and an autonomous consent-modal breaker. No promises — anti-bot is an arms race — but it is **not** naive headless emulation. **Can I point it at my existing Playwright test suite?** No. This isn't a test driver; Playwright remains excellent for deterministic suites. Grade Eleven is an agent-facing browser an LLM operates. **Where does memory live?** Locally, in LanceDB ("Cortex"): harvested pages and vaulted scripts are embedded and semantically recallable, so your agent keeps research context across sessions without a hosted vector store. **Is it production-ready?** No — it's an experimental prototype for local AI research. That's rather the point. > **Punk ethos, not carte blanche.** Owning your tooling doesn't change the law: the **RESEARCH PURPOSES ONLY** terms at the top of this README still apply. The point is _ownership and readability_, not immunity. --- ### 🎯 Core Architecture Principles 1. **100% Real Browser Chassis:** No headless emulation, synthetic user-agent spoofing, or sandboxed scraping. Hyperbolic Browser runs a full-fledged, visible Chromium instance (`headless: false`) with hardware acceleration, audio/video capabilities, and authentic cookie/session persistence. 2. **Multimodal Vision Integration:** Specifically tailored for multimodal models (e.g. Bonsai 2 27B). The agent takes high-res viewport screenshots (`take_screenshot`) to visually understand layouts, buttons, and dynamic canvas states, and can act directly by coordinate, selector, or mark badge (`act`). 3. **Full Developer Console & Script Execution:** Gives the agent full console access (`get_console_logs`) to inspect runtime errors and API output, plus arbitrary JavaScript evaluation (`evaluate_javascript`) to interact with complex SPAs. 4. **Behavioral Bot Detection Bypass:** Bypasses Cloudflare, Akamai, Datadome, and behavioral bot sensors by avoiding synthetic `element.click()` events (`isTrusted: false`). Instead, it dispatches **real input events over the Chrome DevTools Protocol** (`Input.dispatchMouseEvent` / `Input.dispatchKeyEvent` / `mouseWheel`) accompanied by organic cubic Bézier pointer movement and human Gaussian typing cadence. CDP delivery is **focus-independent** — it lands even when another application owns the OS foreground — with `webContents.sendInputEvent` kept only as a fallback. --- ## 🎨 Theme & Cyberdeck Interface Built with **Tailwind CSS v4** and **DaisyUI 5**: - **Custom Theme:** `mark-eleven` - **Color Inspiration:** Antigravity electric cyan (`oklch(75% 0.18 215)`), VS Code workspace slate (`oklch(21% 0.012 250)`), and Photoshop deep charcoal neutrals. - **DaisyUI Components:** - `navbar` & `mockup-browser` address bar with real-time navigation and SSL/protocol status. - `status` and `badge` indicators reflecting live agent lifecycle (`IDLE`, `TRAVERSING`, `SIMULATING_INPUT`, `HARVESTING`). - `tabs` (`tabs-border`) for switching between **Telemetry Kinematics**, **Construct Terminal**, and **MCP Matrix Logs**. - `stats` / `stat` blocks tracking coordinates, Bézier velocity, tokens saved, and interaction counters. - `mockup-code` for viewing synthesized Markdown memory constructs with token downsampling ratios. --- ## 🕹️ Ghost Cursor Telemetry Engine - **Organic Bézier Trajectories:** Natural cubic Bézier curve calculation with quintic ease-in/ease-out acceleration, micro-jitter, and target deceleration. - **Focus-Independent CDP Delivery:** Input events are dispatched over the tab's already-attached Chrome DevTools Protocol debugger (`Input.dispatchMouseEvent` / `Input.dispatchKeyEvent` / `Input.mouseWheel`), with `Emulation.setFocusEmulationEnabled` so focus-gated page JS still responds. Clicks, keystrokes, and momentum wheel scrolling land **regardless of which window owns the OS foreground**. `webContents.sendInputEvent` remains only as a fallback (and only that path needs the window focused). The active transport is reported by `bridge_health` → `input.transport` (`cdp` | `native`). - **Anti-Bot Defense Bypass:** Avoids heuristic bot triggers by behaving like an authentic human operator; every interaction is `isTrusted: true` because it is genuine browser input, not a synthetic DOM `.click()`. --- ## 🎛️ Focus-Independent Input & Background Rendering Two real-desktop failure modes are handled explicitly so long harvests and HIL flows stay reliable: - **Input is not tied to OS focus.** Synthetic input is delivered over CDP and therefore reaches the renderer even while you work in another application. If the debugger is unavailable the simulator falls back to `webContents.sendInputEvent` and brings the window forward first (that path is the only one that steals the foreground). `bridge_health` exposes `input.transport` so an agent can tell which path is live. - **Occluded windows keep rendering.** Browsing tabs run with `backgroundThrottling: false`, and the app boots with `--disable-backgrounding-occluded-windows`, `--disable-renderer-backgrounding`, and `--disable-background-timer-throttling`. Without these, Chromium reports the page `hidden`, throttles timers to ≥1s, and stops producing frames — so `scroll` events never fire and `IntersectionObserver`/rAF hydration stalls (the classic "lazy list stops growing" bug). - **Viewport gating is explicit.** Real input needs a non-zero viewport; a fresh or hidden tab can briefly report `0x0`. Call `set_window_visibility({ visible: true })` and wait for a non-zero viewport before acting. Showing the window is otherwise only needed to make it visible to a human (HIL). --- ## 🧩 Orthogonal Primitive Layer The older tool list is being consolidated onto **a few orthogonal verbs** - one observation model, one action model, one wait model - with the flat tools becoming projections. All primitives run on the TIER-1 humanlike path (real input events; no page DOM mutation beyond Hyperbolic Browser's own `data-mark-id` stamp). | Primitive | Job | Replaces | | :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------- | | `observe(as, region, budget, cursor)` | One budgeted, cursor-paged observation model (`markdown`/`text`/`ax`/`som`/`list`/`table`/`app_data`) | `get_page_markdown` + `snapshot_rendered_page` + `list_marks` | | `act(mark_id \| selector \| x+y, action, text, secret, await_conditions, dry_run)` | Unified humanlike click/focus/hover/type/press on a **mark ref, CSS selector, or coordinate** **+ optional post-conditions + delta report** | `click_mark`/`type_mark`/`click_element`/`type_text` plus a following wait | | `wait_for(conditions, require, timeout_ms)` | Declarative readiness gate — the primitive that replaces blind sleeps | every `sleep`/"did it load?" guess | | `expect(conditions)` | Immediate assertion (no polling) with per-condition evidence | agent-side guessing | | `find(role, name, contains, regex, tag, selector)` | Semantic element search → **refs** (mark ids) | hand-written CSS/XPath | | `extract(kind, ref, selector)` | Structured reads: repeating `list` rows, `table` records, embedded `app_data` | regex over HTML | | `collect_all(selector, scroll, max_scrolls)` | Scroll a lazy/virtualized list to the end and dedupe rows in **one call** | a manual scroll-and-harvest sweep | | `page_state()` / `diff(since)` | Cheap monotonic change signature + field-by-field diff for loops | re-reading the whole page | | `bridge_health()` | Liveness, `capabilities[]`, `revision`, `window`, `input.transport` | assuming the bridge is up | | `export_har(pattern, save)` · `context_*` | HAR 1.2 export · named cookie/storage profiles | ad-hoc replay · manual session juggling | **Refs are marks.** A ref _is_ a Set-of-Marks badge id — `find` returns rows carrying the `mark`, and `act(mark_id=…)` consumes it (re-resolving the live centre each time). When there is no badge, the **same** `act` also takes `selector="…"` or `x=`/`y=` — one action tool, three address modes. **Wait vocabulary:** `selector` · `gone` · `text`/`regex` · `url` · `role_name` · `count(min/equals/max)` · `network_idle` · `stable(marks|height|text|nodes)` · `revision`. **Structured errors:** new endpoints return a machine code (HTTP 400) — `STALE_REF` (re-scan and re-issue), `TIMEOUT`, `NO_TARGET`, `BAD_REQUEST`, `NOT_SUPPORTED`. > Full recipes (R1–R5), the wait table, and the error catalogue live in the OKF partition [`kuang_docs/partitions/primitives_and_workflows.md`](./kuang_docs/partitions/primitives_and_workflows.md), also readable as the MCP resource `mark-eleven://okf/partitions/primitives-and-workflows`. --- ## 📄 Token-Efficient Construct Harvester - **Pure Node.js:** Powered by Mozilla Readability and Turndown. No external Python or platform-specific binaries required. - **Composed-DOM capture:** Serialisation walks _through_ open shadow roots and bakes live form state (`value`, `checked`, `selected`) into attributes, so web-component forms — signup and login pages especially — are actual content instead of empty custom-element tags. Password values are recorded as a length, never a value. - **Semantic Flattening:** Strips ads, navigation sidebars, and script clutter. Links and images resolve to absolute URLs. - **Honest, stable envelope.** Front-matter carries only what changes the reading of the body — no timestamp (so two harvests of an unchanged page are byte-identical and can be diffed or paged), no byte-ratio vanity metric: ```yaml --- url: "https://example.com" title: "Example Domain" reader: "readability" extracted_chars: 2140 page_chars: 5410 shadow_roots: 2 --- ``` `reader` names the extraction path; `extracted_chars` and `page_chars` are the same unit (characters of page text), so coverage is comparable. A partly-visible page says so, and names the alternates, instead of looking short. - **Pageable by default:** `observe(as:"markdown")` returns a 25,000-character view; `budget` + `next_cursor` page through the rest, and `budget: 0` returns the whole construct. --- --- ## 🧠 LanceDB Persistent Cortex & Semantic Recall Hyperbolic Gateway features an embedded, serverless vector database (**LanceDB**) combined with Tantivy-powered Full-Text Search (BM25) stored locally under `./data/cortex/`. - **Auto-Harvest on Navigation:** Every web page visited is automatically chunked, embedded, and indexed into the `page_history` table in the background. - **Hybrid Semantic Recall:** Models can invoke `recall_memory` to execute hybrid vector + BM25 search across past research sessions, retrieving verbatim snippets, page titles, and relevance match scores. - **Persistent Bookmarks:** Save critical research nodes, documentation hubs, or matrix targets with semantic tags and research notes. - **DaisyUI 5 Cortex HUD:** Open the Cortex modal (`🧠 CORTEX`) from the navbar to browse recent history, execute live semantic queries, or manage bookmarked cards. --- ## 📑 Hardware-Accelerated Multi-Tab Browsing - **Electron `WebContentsView` Isolation:** Independent navigation state, separate history stacks, and zero-flicker view swapping. - **Automatic Popup Trapping:** Links configured with `target="_blank"` or `window.open` are cleanly trapped into managed child tabs rather than escaping as detached OS windows. - **Dynamic DaisyUI 5 Tab Bar Strip:** Real-time loading spinners, active indicators, title truncations, and memory reclamation upon tab closure. --- ## 🛡️ Autonomous Shield-Breaker (Cookie & GDPR Destroyer) - **Zero-Token Modal Clearance:** Saves 1–2 LLM tool calls on almost every new domain. - **Preload Framework Detection:** Detects OneTrust, Cookiebot, Google GDPR (`#L2AGLb`), TrustArc, and generic consent frameworks. - **Bézier Dismissal:** Dispatches authentic Bézier cursor movement and hardware clicks to "Accept All" or "Agree" before notifying the agent that the page is ready. - **Manual Directive:** Agents can also manually call `dismiss_consent` whenever unexpected overlays block the viewport. --- ## 🎯 Set-of-Marks (SoM) Visual Grounding - **Zero Coordinate Hallucination:** Completely eliminates hallucinated pixel coordinates or fragile CSS selectors. - **Shadow-DOM aware:** Badges are collected through **open shadow roots**, so controls inside web components (login/signup forms, design-system dialogs) get marks like any light-DOM element — occlusion is tested with the deepest hit and composed containment, not `elementFromPoint` alone. Only `mode:"closed"` roots stay opaque. - **High-Contrast Neon Badges:** Ephemerally injects high-contrast amber neon numbered badges (`[1]`, `[2]`, `[3]`, etc.) over every visible, interactable DOM element (``, `