Skip to main content

​
MonoSurf

MonoSurf gives an AI a direct, CLI-first connection to a real Chromium page. It can read public pages, work inside persistent login sessions, collect growing feeds, capture network responses, run browser QA checks, and execute reusable site actions through Chrome DevTools Protocol (CDP). Verified against monosurf 0.11.3, OpenCLIs build 2026-07-19-222928. Version 0.11.3 keeps lib-monosurf as the reusable agent-facing facade and makes managed launch ownership collision-safe. A new profile skips active unregistered ports, verifies the exact chosen port before committing its record, retries temporarily unavailable ownership metadata only for a bounded interval, and fails closed when ownership cannot be proved. The facade owns the canonical help, embedded docs, and profile TUI; the core owns the typed plan, routing, browser lifecycle, and CDP engine.
Standalone MonoSurf and kernel-cli websurf call the same lib-monosurf facade and lib-monosurf-core engine in-process. They own the web page: DOM, JavaScript, page network traffic, and profile-backed login sessions. Kernel CLI owns the operating system around it: browser chrome, native dialogs, permission prompts, and other desktop applications.The current standalone release and Kernel CLI 0.26.8 both expose MonoSurf 0.11.3. The two executables share the same command/state contract but are not byte-identical; their binaries remain independently versioned and published.

​
Quick Start

If Kernel CLI is already installed, the embedded entry point provides the same engine and state without requiring a separate MonoSurf installation:
For a logged-in site, create a named profile, sign in through the browser window, and grant the matching access scope:
The site can still expire or challenge a session. “Persistent” means the real browser profile survives process restarts and reboots; it does not override a site’s own security policy. For an explicit cookie-only bootstrap from Chrome:
This path requires the shared ~/.niia/bin/monolex-native-host staged by the Monolex desktop app (monolex-native-host.exe on Windows). The standalone monosurf 0.11.3 archives do not bundle that host. Without it, bridge install returns non-zero even though extension assets may already have been materialized; that partial state is not a completed installation. The fixed-ID extension stores a vault snapshot after a user clicks Sync. A later site command hydrates only an empty live jar, before navigation, with explicit-origin cookies and preserved attributes. Invalid scope or any CDP error aborts the command. This does not copy localStorage, IndexedDB, service workers, passwords, a Chrome profile, or the Chrome process. The Monolex Agent Browser’s managed login is the separate same-profile route for full state.

​
What MonoSurf Owns

Browse and Attach

Open a clean temporary browser, use a named persistent profile, or attach to an existing CDP endpoint.

Profiles and Login

Keep isolated browser identities, choose a default, and guard cookie compatibility by pinning the browser engine.

Harvest and Network

Stream feed items as JSONL while separately recording media, XHR, and CDN responses that the DOM may not expose.

Web QA

Capture screenshots, console output, network failures, selector waits, smoke assertions, and responsive viewports from one command.

Site Plugins

Package site-specific read and write workflows as discoverable JSON commands without rebuilding the CLI.

Safety and Health

Use time-limited grants, strict TLS, verified CDP-port ownership, read-only health reports, explicit cleanup classes, and offline regression tests.

​
Three Connection Modes

Bare browse remains temporary unless MONOSURF_PROFILE or a persistent default profile has been selected. Add --ephemeral when a clean one-off session must override that default.

​
The Page and OS Boundary

A file-upload flow shows the handoff clearly:
  1. MonoSurf fills the web form and activates the page’s upload control.
  2. The operating-system file picker opens outside the page and outside CDP.
  3. Kernel CLI resolves the native picker, enters the path, and presses Open.
  4. MonoSurf resumes at the page, waits for the uploaded state, and verifies it.
Use Kernel CLI’s complete command reference when the browser workflow leaves the page surface.

​
Companion Tools

MonoSurf does not bypass a website’s terms, bot defenses, access controls, or rate policies. It replaces a platform-specific API integration with a real browser connection; the website remains the authority for permitted access.

​
Where Next

Usage and Command Reference

Learn every supported command family, connection mode, option group, and safety boundary in MonoSurf 0.11.3.

Site Plugins

See how installed domains expose reusable read and write commands.

Auth Gate

Understand read/write grants and protected browser-session access.

Kernel CLI

Continue a workflow through native dialogs, browser chrome, or another desktop application.