How MonoSurf Works

MonoSurf is a Rust-native client for Chrome DevTools Protocol (CDP). Standalone monosurf and embedded kernel-cli websurf share the lib-monosurf facade for canonical help, docs, and the profile TUI, then call the same lib-monosurf-core engine. The engine connects directly to a Chromium page for navigation, JavaScript, DOM extraction, screenshots, console and network evidence, and selector-based verification. Verified against monosurf 0.11.3, OpenCLIs build 2026-07-19-222928.

The Core Loop

CLI request
    ↓
choose who owns the browser session
    ↓
connect to Chromium through CDP
    ↓
configure page evidence before navigation
    ↓
navigate, wait, read or act
    ↓
emit output and a meaningful exit code
    ↓
close an ephemeral session or retain a managed one

MonoSurf does not require Node.js or a Playwright process to run its normal CDP page loop. It can still discover Chromium builds installed by Playwright or Puppeteer and use those browser binaries as engines.

Choose a Session

Session	How it is selected	Who owns lifecycle and persistence
Ephemeral browse	`monosurf browse <url>` after no explicit, environment, or default profile is selected	MonoSurf launches it, removes its temporary profile on close, and discards login state.
Managed profile	`--profile`, `MONOSURF_PROFILE`, or `profile use`	MonoSurf owns the named browser profile; its login state survives close and reboot.
External CDP	`--cdp-url <endpoint>`	The external Electron, WebView2, Tauri, or Chromium process owns the browser; MonoSurf only attaches.

For site-plugin commands, the full profile ladder can also select the single registered profile or ask a person on an interactive terminal. Browse ends in ephemeral mode instead of silently adopting that single profile.

Managed Profile Lifecycle

profile new work
      ↓
profile exists, browser stopped, login state retained
      ↓
start or any profile-backed command
      ↓
browser running and CDP ready
      ↓
stop, window close, or machine reboot
      ↓
browser stopped, login state still retained
      ↓
profile rm work
      ↓
login state deleted after confirmation

The first successful launch pins the browser kind and signing identity that protect the profile’s encrypted cookies. If discovery later resolves a different kind, the launch fails clearly. --allow-binary-change accepts the new engine and the likely need to sign in again.

Managed CDP port ownership

An open TCP port is not ownership proof. MonoSurf 0.11.3 reads the listener command line and looks for the exact, boundary-aware --user-data-dir argument of the selected profile. A new unregistered profile first skips active ports, then carries the exact selected port through launch verification and failed-launch cleanup instead of allocating a second time after Chrome binds:

Classification	`start` or profile-backed connect	`stop` port fallback
Owned	Reuse the listener and repair the pid record when needed.	Signal the verified listener.
Foreign	Fail with pid and command-line evidence; suggest explicit `--cdp-url` when attach was intentional.	Refuse to signal it.
Unknown	Retry only while OS metadata may still be settling, then fail closed; no ownership proof means no connection.	Fail closed; no ownership proof means no signal.

A live pid-file number whose readable command line belongs to another process is treated as a recycled pid: MonoSurf removes the stale record and never signals that process. Listener discovery also asks for the process in LISTEN state, avoiding a connected CDP client socket being mistaken for the browser server. A known foreign owner is refused immediately. Unknown ownership gets a bounded one-second settle window; it never turns into implicit trust. Explicit browse --cdp-url <endpoint> is the separate intentional foreign-attach path. monosurf login <domain> keeps the authenticated browser session and can save an encrypted session snapshot as a bootstrap backup. The explicit bridge path (bridge install, then bridge [domain] [--keep] before a user clicks Sync) stores the active tab’s matching cookies through the same protected snapshot boundary. It is available only when Monolex desktop has staged the shared ~/.niia/bin/monolex-native-host (.exe on Windows); the standalone 0.11.3 archive does not contain that prerequisite.

site command needs a session
          ↓
does the managed profile already have live cookies?
          ├── yes → use the live browser session
          │         server-side token rotation stays current
          └── no  → require the grant, read the protected snapshot,
                    validate every scope, hydrate the empty cookie jar with
                    explicit-origin cookies, then continue

Hydration happens before navigation, preserves domain/path, HttpOnly, Secure, SameSite, and expiry, and fails on any invalid scope or CDP write error. Login does not empty the browser jar after saving a snapshot; a live session wins. The bridge copies cookies only. It 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 reuse path.

Browse Execution

Browse builds one page session and layers the requested work onto it:

Resolve ephemeral, managed-profile, or external-CDP ownership; a managed listener passes the exact-port ownership guard before attachment.
Configure viewport, console capture, and network logging before navigation.
Navigate under strict TLS unless --insecure was explicitly requested.
Wait for asynchronous content when --wait is present.
Capture screenshots, console messages, network health, or expectations.
Produce text, structured extraction, evaluated JavaScript, or collected JSONL.
Return non-zero when the requested output, expectation, navigation, or write fails.
Tear down only the session MonoSurf owns.

--timeout is the deadline of the work requested by the command: selector waits and expectations use it, and evaluation or extraction uses a deterministic deadline rather than waiting indefinitely. postcondition navigation binds one exact normalized-text control to the evidence expected after its real CDP click: canonical URL/history, scroll, viewport intersection, destination target text, and fixed-header clearance. Duplicate controls, covered/off-screen or missing targets, URL drift, and timeouts fail closed. postcondition toast applies the same one-write/one-proof model to a visible toast when success intentionally keeps the URL unchanged.

Harvest and Network Capture

Collection and network logging observe different evidence in the same pass:

page navigation
      ├── DOM collection loop
      │     extract new items → deduplicate → stream JSONL → scroll
      │                                      ↓
      │                       no growth → bounded recovery → stall_reason
      │
      └── CDP network listener
            stream document, media, XHR, and CDN responses as JSONL

The collection output flushes item by item, so an interrupted long run retains the items already written. The final report states why the loop stopped.

Site Plugin Execution

A site command adds a reusable contract around the page loop:

domain + command
      ↓
load and verify the installed plugin
      ↓
check read or write grant
      ↓
connect to the selected profile and resolve live login state
      ↓
navigate → wait → run declared actions → extract → format

Supported action shapes are:

Action	Purpose
`click`	Activates an element selected in the page.
`type`	Enters substituted text using the command’s declared input method.
`wait`	Waits for a selector between steps.
`sleep`	Adds a deliberate fixed delay when no state signal exists.
`js`	Runs a page-context JavaScript expression through CDP.

Legacy JSON may still parse a pw action and the installed plugin help may list it for compatibility. CDP mode does not execute that action; convert it to a supported js, click, type, or wait sequence.

Browser Selection

monosurf browsers
monosurf start --profile work --browser 2
monosurf profile info work

Engine family	Typical use	Important boundary
System Chrome	Visible login and daily profile use	Sites can still apply automation challenges.
Playwright/Puppeteer Chromium	Headless and repeatable automation	MonoSurf uses the browser binary directly; those packages are discovery sources, not the normal control process.
External CDP endpoint	Existing desktop app or debug browser	MonoSurf does not manage the external process or profile.

No browser engine bypasses a website’s access rules, bot defenses, or rate policies.

Outside the Page

CDP cannot see native file pickers, print/save dialogs, Face ID or Keychain prompts, browser tabs and menus, or another desktop application. Hand those surfaces to Kernel CLI, then return to monosurf or kernel-cli websurf to verify the page result.

Usage and Command Reference

See every supported command family, option group, and exit boundary.

Kernel CLI

Continue through native observation, accessibility, OCR, input, apps, and windows outside the page.

Get Started

Articles

So Anthropic

User Guide

Philosophy

Applied Philosophy

Architecture

Gestalt Color

Transparency

Terminal Core

Features

VariableMD

Research

CodexMono

OpenCLIs

vpncli

MonoSurf

AI-CLIs

How It Works

How MonoSurf Works

The Core Loop

Choose a Session

Managed Profile Lifecycle

Managed CDP port ownership

Browse Execution

Navigation Postcondition

Harvest and Network Capture

Site Plugin Execution

Browser Selection

Outside the Page

Usage and Command Reference

Kernel CLI

​How MonoSurf Works

​The Core Loop

​Choose a Session

​Managed Profile Lifecycle

​Managed CDP port ownership

​Login State: Live Session First

​Browse Execution

​Navigation Postcondition

​Harvest and Network Capture

​Site Plugin Execution

​Browser Selection

​Outside the Page

Usage and Command Reference

Kernel CLI

How MonoSurf Works

The Core Loop

Choose a Session

Managed Profile Lifecycle

Managed CDP port ownership

Login State: Live Session First

Browse Execution

Navigation Postcondition

Harvest and Network Capture

Site Plugin Execution

Browser Selection

Outside the Page