⚡ Hyperbolic Gateway

The Local Web Browser for Your AI Agents

"I'll hack the Gibson"
— Dade Murphy (AKA Crash Override), Circa 1995

🧭 Index

• About — What it is · A punk-ethos alternative to browser clouds
• The deck — Theme & Cyberdeck UI · Ghost cursor telemetry · Focus-independent input · Multi-tab browsing
• Reading the web — Orthogonal primitive layer · Construct harvester · Set-of-Marks
• Driving the web — Shield-breaker · Form filler · Human-in-the-loop
• Memory & data — Cortex · Downloads · Session vault · Script vault · Timelapse recorder
• Inspection — Network & API streams · WebSocket & SSE
• Operating it — System tray · MCP tools (63 advertised) · REST wrappers
• Building on it — Architecture lowdown · Codebase & docs · Quickstart · Testing · OKF knowledge
• Optional decision layer — decide / drive design notes · Control layer: targeting, consent, human takeover · Shadow DOM & iframes: what Hyperbolic Gateway can see and click · Shadow Walk: sealed-content plan · Field notes from dogfooding · Changelog
• Release notes — What shipped · All releases
• Lore — Neuromancer inspiration

🕶️ 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.

_{Open the 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 — 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.

🤘 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 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

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

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, 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:

  ---
  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 (<a>, <button>, <input>, select, [role="button"]).

• Precision Multimodal Actuation:

  1. take_screenshot({ marks: true }) captures the badge overlay and returns an element lookup table ({ id: 1, tag: "BUTTON", text: "Submit", bbox: [...] }).
  2. act(1) moves the Bézier ghost cursor to the element's centroid with sub-pixel accuracy and clicks.
  3. act(2, action: "type", text: "cyberdeck") focuses the input and types text with human cadence.

• One tool, three cost tiers via take_screenshot({ marks: true, detail: … }) (pick the cheapest that fits your model):

  detail	Payload	Use when
  "full" (default)	Marks table + full-resolution PNG	Vision model, fine visual detail matters
  "economy"	Marks table + 640px-wide JPEG (q45), roughly 10-20x smaller	Vision model, tokens/bandwidth matter
  "markdown"	Marks table only, no image	Text-only models (e.g. local GGUFs) or the cheapest page scan

  All three return the same mark IDs, so act(mark_id, …) works after any of them. Text-only models must not be sent images: a base64 PNG inlined into the prompt can be 100k+ tokens and will stall local inference servers.

📝 Single-Turn Batch Form Filler

• Instantaneous Multi-Input Population: Fills complex checkout forms, flight booking screens, or multi-field search bars in a single turn without round-trip LLM latency.
• Human Typing Cadence: Simulates variable human inter-key delays (60–240ms) with Gaussian jitter between fields.
• Flexible Field Types: Supports text inputs, password fields, dropdown <select> menus, checkboxes, and radio buttons with optional automatic form submission (submit_selector).

📥 Download Manager & Cortex Harvester

• Workspace-Local Routing: Intercepts Chromium's will-download session events, routing all files into ./data/downloads/ rather than the OS user folder.
• Automated Text Extraction: Automatically extracts clean Markdown text from downloaded PDFs (pdf-parse), CSVs, and JSON files.
• LanceDB Vector Ingestion: Automatically ingests downloaded document text into the LanceDB Cortex vector store for instant conversational recall.
• MCP Inspection: list_downloads and read_download(filename) allow agents to inspect and read downloaded files on demand.

🎥 Timelapse Recorder

• Records the deck itself: the REC button (next to SETTINGS) captures the Cyberdeck window as a timelapse — frames every intervalMs, played back at a chosen fps. One minute of work becomes two seconds of video at the 1 fps / 30 fps defaults.
• True re-timing, not a sped-up screen recording: the renderer uses WebCodecs VideoEncoder with explicit frame timestamps and muxes VP9 into WebM with webm-muxer (MediaRecorder cannot retime frames).
• Settings → Recording: enable/disable, output directory with BROWSE…, capture interval, playback fps, max width and bitrate; finished files are listed with COPY PATH.
• Agent access is a separate, human-only switch: "Let agents use the recording tools" removes record_start, record_stop and list_recordings from tools/list and makes the bridge refuse them with RECORDING_TOOLS_DISABLED. Only the Settings panel can flip it — no tool or HTTP route writes that flag.
• Programmatic hand-off: record_start → record_stop returns the absolute .webm path (plus size, frames and speed-up), and list_recordings lists recent files newest-first. That path is a plain string you can type into a file-upload field; if the field only opens a native picker, hand it to a human.
• Why a path matters: upload forms usually cannot be driven by setting a value - the browser requires a real file selection. Hyperbolic Gateway gives the agent (or the human) the exact file to choose instead of guessing.

🔐 Session & Cookie Jar Vault

• Stateful Auth Persistence: Captures and restores active session cookies, localStorage, and sessionStorage into encrypted/structured snapshots under ./data/sessions/<name>.json.
• Bypass 2FA & Logins: Resume authenticated states on GitHub, airline portals, news sites, or internal dashboards across agent sessions without triggering repetitive logins or CAPTCHAs.
• MCP Tools: context_save(name), context_open(name), context_list(), and context_delete(name).
• Legacy aliases: save_session(name) / restore_session(name) / list_sessions() still work (same vault) but are hidden from tools/list.

📡 Live Network & API Stream Interceptor

• Direct Chrome DevTools Protocol Wire: Attaches directly via CDP (Network.enable) to monitor all incoming and outgoing network traffic.
• Direct JSON Extraction: Bypasses DOM scraping entirely for modern Single-Page Applications (SPAs like Twitter, Reddit, Skyscanner). Captures completed XHR/Fetch response bodies (Network.getResponseBody).
• MCP Inspection: get_network_traffic filters requests by URL pattern or method, and query_json_data({ source: "network_payload", source_id }) returns parsed JSON (sliced by path/view) directly into the LLM context.
• Action-Correlated Capture: get_network_traffic({ since: 'last_action' }) returns only the requests fired by the most recent mutating action (also accepts an epoch-ms timestamp or a page revision). export_har writes a HAR 1.2 log of captured traffic for offline replay.

⚡ Real-Time WebSocket & SSE Interceptor

• Duplex Stream Surveillance: Captures duplex frames across persistent wss:// WebSockets and Server-Sent Events (text/event-stream).
• Auto-Parsed Payloads: Automatically detects and parses JSON streaming frames from live crypto tickers, chat platforms, financial feeds, and streaming LLM APIs.
• In-Memory Ring Buffer: Rolling buffer of 500 frames with filtering by stream ID, direction (sent / received), and message limit.
• MCP Tools: list_realtime_streams and clear_capture({ scope: "streams" }); inspect frames with query_json_data({ source: "stream_messages", source_id }).

💾 Script Vault & LanceDB Semantic Macro Engine

• Reusable Automation Macros: Store, recall, and execute custom JavaScript DOM extraction and automation scripts under ./data/scripts/<name>.json.
• Vector-Indexed Semantic Recall: Every vaulted script is automatically embedded into the LanceDB scripts table. Models can recall scripts using conversational natural language queries (list_scripts({ query: "extract table rows as json" })).
• Parameter Injection: run_script(name, args) executes vaulted scripts inside the active tab with dynamic runtime arguments and closure isolation.

🗔 System Tray & Background Minimization ("Out of the Way")

• Unobtrusive Background Operation: Keeps the Cyberdeck running completely out of the way in the Windows notification tray during long-running automated tasks, batch scrapes, and research pipelines.
• Single-Click Summon: Left-clicking or double-clicking the system tray icon toggles window visibility instantly.
• Close-to-Tray Protection: Closing the window (X) minimizes to the system tray rather than killing active background tasks and MCP sessions.
• MCP Tools: set_window_visibility({ visible?, focus? }) and configure_system_tray({ close_to_tray }).

🚨 Human-In-The-Loop (HIL) Intervention Protocol

• Graceful Human Collaboration: When the agent hits Cloudflare Turnstile, CAPTCHAs, 2FA/SMS OTPs, or payment confirmations, it invokes request_human_intervention.
• Multi-Channel Alerting:
  1. OS Native Desktop Notification: Fires an urgent desktop notification banner with sound.
  2. Window Summon & Taskbar Flash: Automatically restores the window from the tray, brings it to the front, and flashes the Windows taskbar amber (flashFrame(true)).
  3. Interactive In-Page Cyberdeck Banner: Injects an amber neon cyberdeck banner (#__kuang_hil_banner) directly into the active webpage with a "RESUME AGENT (DONE)" button.
  4. HUD Action Indicator: Changes the status badge to AWAITING_INPUT with live prompt text.
• Instant Unpause: When the user completes the action and clicks "DONE", the agent immediately resumes its autonomous turn.
• MCP Tools: request_human_intervention, resolve_human_intervention, get_human_intervention_status, and non-blocking send_notification.

🔌 Standardized Semantic MCP Tools (63 advertised · +2 optional)

+2 optional, listed first when active: drive and decide — rows marked ⌥ — appear only when a decision model is configured. The rest of this table is always available.

63 advertised tools (83 registered entries; 23 deprecated aliases are hidden from tools/list but stay callable by name and return a deprecated → use "X" notice — rows marked † below). Seven MCP resources are also exposed: mark-eleven://skills/guide, mark-eleven://tools/recommended, mark-eleven://okf/manifest, and four partition playbooks.

Tier map (mirrors the [TIER n] prefixes the MCP surface puts on the advertised descriptions). TIER 1 · prefer: observe · act · wait_for · expect · find · extract · collect_all · page_state · diff. TIER 2 · fallback: take_screenshot · snapshot_rendered_page · press_key. TIER 3 · use deliberately: evaluate_javascript — powerful, just not the default. Every other tool is unprefixed — it is the only way to do its job. Start with observe → act → wait_for → find → extract/collect_all; the Primitives & Abstraction block is listed first for exactly that reason. Editing this table? Run npm run manual:tools to regenerate the default-tab Manual's collapsible full list from it.

🔌 REST wrappers (hb-rest)

A second, separate MCP server for turning a REST endpoint into a saved, typed tool. It is deliberately not mixed into the browser server: hb-rest ships its own binary, its own stdio process, its own config entry and its own bridge token.

What it is for: agent access to JSON APIs (dashboards, internal tools, SaaS). The wrapper author — human or agent — defines the request once: method, URL, typed arguments, a response recipe, and a credential name. The agent then calls flat arguments; it never assembles a URL, a header set, or a body envelope, and it never sees a credential value.

Credentials are human-only and host-bound: a static value, or an OAuth2 client-credentials client that mints and caches a token. Secrets are encrypted with the OS keychain (safeStorage), injected only on an approved host, and never enter the MCP process.

// Settings → MCP Clients → REST wrappers generates an entry like this
{
  "mcpServers": {
    "hb-rest": {
      "command": "node",
      "args": ["<path-to-repo>/bin/wrap-server.cjs"],
      "env": { "HB_WRAP_TOKEN_FILE": "<userData>/wrap/token" },
    },
  },
}

Meta-tools: wrap_list, wrap_get, wrap_secret_list, wrap_derive, wrap_create, wrap_update, wrap_delete, wrap_run, wrap_test, wrap_reload.

[!WARNING] Read the limits before relying on it. No human-approval gate for mutating calls · OAuth2 is client_credentials only · the wrap server does not raise HIL itself (a rejected credential returns AUTH_REQUIRED) · exposeAsTool has no Settings control · 40-tool cap · DNS-rebinding residual risk · the token URL is outside allowedHosts. The full, blunt breakdown — what works, what doesn't, what is untested, what is risky — is docs/HYPERBOLIC_REST.md.

Tests: npm run test:wrap (50 offline) · npm run test:wrap:mcp (11 lifecycle) · npm run test:wrap:live (46 against DummyJSON).

🗺️ Codebase Directory Structure & Documentation

Each folder contains a dedicated README.md detailing its responsibilities, dependencies, and internal workflows:

🚀 Quickstart

Development Mode (with Live Reloading)

pnpm dev

One bridge per port. Dev and installed builds share the default bridge port 4111 (HB_BRIDGE_PORT overrides it). They also have separate single-instance locks, so both can run at once — and the second one's bridge fails with EADDRINUSE, leaving the MCP tools pointed at the other window. Close one, or run the second with HB_BRIDGE_PORT=4112 and set HB_BRIDGE_URL for its MCP server to match.

Production Build & Launch

pnpm run build
pnpm start

MCP Client Configuration (OpenCode, Claude, Cursor, Antigravity, Atomic Chat)

The HUD's Settings → MCP Clients tab generates a correct, copy-ready config for this installation — OpenCode, Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Google Antigravity, Gemini CLI, Atomic Chat, Zed, and the generic mcpServers shape. It fills in the absolute server path and bridge port, and offers two runtimes:

• Bundled (default) - runs the server on Hyperbolic Gateway's own Electron runtime with ELECTRON_RUN_AS_NODE=1, so Node does not need to be installed. Installed builds unpack bin/ out of the asar precisely so this works.
• System Node — node bin/mcp-server.cjs, requiring Node 20+ on PATH.

A minimal Claude-style entry looks like this (the tab generates the real paths):

{
  "mcpServers": {
    "hb-browser": {
      "command": "<path-to-app>/Hyperbolic Gateway.exe",
      "args": ["<userData>\\bin\\mcp-server.cjs"],
      "env": { "ELECTRON_RUN_AS_NODE": "1" }
    }
  }
}

Note: the Cyberdeck must be running (pnpm run dev or pnpm start) so the stdio server can reach the browser instance on http://127.0.0.1:4111. If you run on another port with HB_BRIDGE_PORT, set HB_BRIDGE_URL for the MCP server — the generated snippet includes it automatically. Installed builds copy the server into userData/bin/ (refreshed on update), because resources/ is temporary for portable and AppImage builds.

🧪 Testing

All suites run against the live Cyberdeck on http://127.0.0.1:4111 (start the app first):

Type-check and bundles: npx tsc --noEmit, npm run build, npm run build:mcp.

📚 Documentation & Knowledge (OKF)

• developer/ — the standard OKF v0.2 developer bundle: MCP setup, browser and REST APIs, wrapper/recipe formats, and examples.
• CHANGELOG.md — release history and migration-relevant changes.
• docs/ — the documentation hub: concept lore, subsystem specs, field notes, and the abstraction roadmap.
• docs/PROPOSED_ABSTRACTIONS.md — the primitive-layer design and its status (A1–A6, B, C, D).
• docs/FIELD_NOTES_2026-10-18.md - root-caused findings from hardening the TIER-1 path on real SPAs.
• docs/FIELD_NOTES_2026-10-20_SIGNUP.md - the signup dogfood run: three silent no-ops, and the plan they produced.
• docs/DECISION_MODELS.md - the optional decision layer: decide / drive, guard + elimination, gates, screenshots, and who decides what.
• docs/BUILDING.md - installers for Windows/macOS/Linux, signing (macOS unsigned first), GitHub Releases, and auto-update.
• kuang_docs/ — the OKF bundle (kuang_browser_docs): playbook/reference partitions, also served to agents as standard MCP resources:
  • mark-eleven://skills/guide — the full operational manual.
  • mark-eleven://okf/manifest — the bundle manifest.
  • mark-eleven://okf/partitions/selector-and-som · captcha-and-anti-bot · browser-navigation · primitives-and-workflows.

📦 Release notes

[!NOTE] What's new in 1.4.6 — read_url, and a probe that no longer lies. llm_surface reported recommended: "rendered" — a strategy sitting in the same union as the fetchable representations — so callers read it as "fetch the rendered variant" and got a hard HTTP 400 from llm_fetch. Now recommended is null when the site advertises nothing, and a machine-readable next ({tool:"llm_fetch",as} or {tool:"observe",as:"markdown"}) says what to do instead. Both llm_surface and llm_fetch also report scope (origin | page) and scope_mismatch, so a page request that can only be answered with a site-wide /llms.txt index now says so rather than silently returning the wrong document. New read_url does the whole thing in one call — site-provided Markdown/Text when advertised, otherwise a detached render distilled to Markdown (active tab untouched) — and is paged via max_chars + next_cursor so a long legal page is never truncated. Discovery also picks up page-level Markdown alternates from real <a href="….md"> links on the page, not only a declared <link rel="alternate">. 63 advertised tools. See CHANGELOG.md.

What's new in 1.4.5 — timelapse recording, a human-only tool gate, and a client-config generator. The REC button records the Cyberdeck window as a true timelapse: frames are captured every intervalMs and stamped 1000/fps apart, so one minute of work becomes about two seconds of video at the defaults. record_start, record_stop and list_recordings return the absolute .webm path. A separate, human-only switch removes those tools from tools/list and makes the bridge refuse them. Settings is now a full-viewport, tabbed view (Decision model / Recording / MCP clients); the client tab generates copy-ready configs for OpenCode, Claude Desktop/Code, Cursor, VS Code, Windsurf, Google Antigravity, Gemini CLI, Atomic Chat and Zed, on either the bundled Electron runtime (no Node install) or system Node. 62 advertised tools (+2 optional).

What's new in 1.4.4 — auto-update. electron-updater checks 30 s after startup and every 6 hours, downloads in the background (sha512-verified), installs on quit, and offers RESTART in the HUD. It is off in dev builds and on unsigned macOS. KUANG_BRIDGE_PORT makes the bridge port configurable so a dev build and an installed build can run side by side, and a port collision now names EADDRINUSE instead of failing silently.

What's new in 1.4.2 — a decision model in the loop, and a loop that drives it. This patch adds drive (observe → guarded decide → verified act, one decision call per step, with a typed stop reason and a text hand-off), screenshots for decide (hosted TypeSafe only — the OpenCode gateway drops the image header, so images are disabled there and the result says so), gate hand-offs raised by Kuang itself, consent sweeps at 0.9/2.6/6 s, clickable labels, and selectable HUD text. It builds on the 1.4.0 work: a decision model in the loop, and the evidence that it worked. observe(as:"components") returns a decision-ready table (role, name, value, region, and the actions each component accepts); an optional decide tool asks a typed decision model (Jev 1.13 via OpenCode's Console endpoint, or a local ONNX model) for the operation and target, guarded by confidence, target membership and affordance checks, with rejected options eliminated and retried, and fallback:"agent" when nothing survives. Age verification and CAPTCHA are hard human hand-offs — detected before any model call. Typing gained an input-method ladder (keys → CDP insertText → paste) for fields that ignore keystrokes, act now sees SPA navigations and clicks large card links at a point that belongs to them, and the HUD gained a Settings dialog, a conditional DECISIONS tab, a right-click menu, and a HIL banner that stays off the viewport. Measured: Jev 10/10 on the page bench at ~376 ms. 59 tools (+ decide and drive when configured). See CHANGELOG.md.

What's new in 1.3.0 — the page is now readable and addressable through shadow DOM, and the tool no longer reports success for actions that did nothing. observe(as:"markdown") harvests the composed tree (open shadow roots, live form values, passwords reduced to a length) with a minimal, stable envelope (reader, extracted_chars/page_chars, shadow_roots) and working budget/next_cursor paging; act resolves selectors through shadow roots to the control a mouse would hit, verifies that typing landed (ok:false + TYPE_NO_EFFECT + evidence, distinguishing "input never arrived" from "the control refuses it"), and reports target.field for web-component controls; Set-of-Marks, find and act(mark_id) traverse open shadow roots too. All found by dogfooding a real signup flow — see docs/FIELD_NOTES_2026-10-20_SIGNUP.md. 62 advertised tools. See CHANGELOG.md.

What's new in 1.2.0 — an autonomous discovery layer. llm_surface detects a site's own Markdown/Text representation (/llms.txt, a <link rel="alternate"> hint, or content negotiation) and llm_fetch reads it (gated on an advertised surface); search_web runs multi-engine search in a detached view with automatic fallback; deep_crawl walks a site breadth-first, distilling and indexing every page into Cortex; research_topic searches → gathers → distils → indexes and returns cited extractive evidence. Plus typed JSON-LD (schema_org) and every-table extraction on extract, one shared reusable off-screen view (fixes flaky detached reads), and an explicit TIER 1/2/3 map across the docs and the default-tab Manual. 62 advertised tools. See CHANGELOG.md and TODO_RESEARCH_CRAWL.md.

What's new in 1.1.1 — MCP stdio reliability hardening so the kuang tool namespace can no longer "just go away". Per-call diagnostics now go to the file log only, stderr is a short bounded boot banner (backpressure-aware, 16 KiB hard cap, lines dropped rather than queued), a KUANG_BRIDGE_TIMEOUT_MS ceiling (default 300 s) stops a wedged Cyberdeck from hanging a tool call, and closing stdin shuts the child down cleanly. Reproduced and verified: stderr unread, 600 calls → 601/601 responses, 0 timeouts (was 158 responses then a stall). See CHANGELOG.md and docs/HANDOFF_ORCHA_MCP_STDERR.md.

What's new in 1.1.0 — an orthogonal primitive layer (observe · act · wait_for · expect · find · extract · collect_all · page_state/diff · export_har · context_*) that removes blind sleeps and guessy selectors, focus-independent CDP input (clicks/typing land even when another app owns the foreground), and background-render hardening so occluded windows still hydrate and scroll. 16 new tools, 1 new OKF playbook partition. See docs/PROPOSED_ABSTRACTIONS.md.

📄 License

This project is licensed under the MIT License © 2026 hyperbolictonic.

🌌 Neuromancer Inspiration & Cyberpunk Canon

"A Kuang Grade Mark Eleven penetration program. Icebreaker. The military stuff, the heavy artillery."
— William Gibson, Neuromancer (1984)

In William Gibson's genre-defining cyberpunk masterpiece Neuromancer, console cowboys Case and the ROM personality construct of the Dixie Flatline jack into the Matrix using an Ono-Sendai Cyberspace 7 deck. Their ultimate weapon: the Kuang Grade Mark Eleven—a mythical military-grade icebreaker designed to slice through the impenetrable corporate ICE surrounding the Tessier-Ashpool mainframe.

Hyperbolic Gateway began as a project inspired by that fictional lineage, then was rebranded to its current name. The quote and the original Kuang Grade Mark Eleven reference are preserved here as inspiration; Hyperbolic Gateway is an independent project and is not affiliated with William Gibson, Neuromancer, or the fictional device.

It carries that inspiration into the modern web:

• Piercing the Modern Web's "ICE": Headless automation (Puppeteer, Playwright) is routinely flagged and blocked by Cloudflare, Datadome, and behavioral bot sensors. Hyperbolic Browser provides a tactile, visible Chromium cyberdeck that operates with authentic human telemetry.
• The Ghost Cursor as Neural Trodes: Dispatches organic cubic Bézier pointer movement and Gaussian typing cadences, behaving like an authentic human operator seated at the console.
• The LanceDB Cortex as ROM Personality Construct: Provides persistent semantic recall and memory traces so your local AI agent retains research context and bookmarks across browsing sessions.