> ## Documentation Index > Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt > Use this file to discover all available pages before exploring further. # How It Works > How MonoSurf 0.11.3 proves exact browser ownership, imports an explicit cookie snapshot, connects through CDP, binds page writes to evidence, and hands native UI to Kernel CLI. # 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 ```text theme={null} 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 ` 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 ` | 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 ```text theme={null} 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 ` is the separate intentional foreign-attach path. ## Login State: Live Session First `monosurf login ` 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. ```text theme={null} 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: 1. Resolve ephemeral, managed-profile, or external-CDP ownership; a managed listener passes the exact-port ownership guard before attachment. 2. Configure viewport, console capture, and network logging before navigation. 3. Navigate under strict TLS unless `--insecure` was explicitly requested. 4. Wait for asynchronous content when `--wait` is present. 5. Capture screenshots, console messages, network health, or expectations. 6. Produce text, structured extraction, evaluated JavaScript, or collected JSONL. 7. Return non-zero when the requested output, expectation, navigation, or write fails. 8. 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. ## Navigation Postcondition `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: ```text theme={null} 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: ```text theme={null} 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 ```bash theme={null} 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](/kernel-cli), then return to `monosurf` or `kernel-cli websurf` to verify the page result. See every supported command family, option group, and exit boundary. Continue through native observation, accessibility, OCR, input, apps, and windows outside the page.