> ## 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.
# MonoSurf
> Rust-native browser connection and automation for public pages, persistent login sessions, site plugins, feed collection, network capture, and web QA.
# 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](/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
```bash theme={null}
openclis install monosurf
monosurf version
monosurf browse https://example.com --extract
```
If Kernel CLI is already installed, the embedded entry point provides the same
engine and state without requiring a separate MonoSurf installation:
```bash theme={null}
kernel-cli websurf --version
kernel-cli websurf browse https://example.com --extract
```
For a logged-in site, create a named profile, sign in through the browser
window, and grant the matching access scope:
```bash theme={null}
monosurf profile new work
monosurf start --profile work
monosurf auth grant read 1h
monosurf x trending --profile work
```
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:
```bash theme={null}
monosurf bridge install
monosurf bridge example.com # add --keep for repeated Sync clicks
```
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
Open a clean temporary browser, use a named persistent profile, or attach
to an existing CDP endpoint.
Keep isolated browser identities, choose a default, and guard cookie
compatibility by pinning the browser engine.
Stream feed items as JSONL while separately recording media, XHR, and CDN
responses that the DOM may not expose.
Capture screenshots, console output, network failures, selector waits,
smoke assertions, and responsive viewports from one command.
Package site-specific read and write workflows as discoverable JSON
commands without rebuilding the CLI.
Use time-limited grants, strict TLS, verified CDP-port ownership, read-only
health reports, explicit cleanup classes, and offline regression tests.
## Three Connection Modes
| Mode | Command shape | Persistence | Best for |
| ------------------- | -------------------------------------------- | ------------------------- | ---------------------------------------------------------------- |
| Ephemeral browse | `monosurf browse ` | Deleted on close | Public reading, isolated QA, one-off extraction |
| Managed profile | `monosurf browse --profile work` | Survives close and reboot | Authenticated browsing and repeat workflows |
| External CDP attach | `monosurf browse --cdp-url ` | Owned by the external app | Electron, WebView2, Tauri webviews, or an existing debug browser |
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
```text theme={null}
Website DOM, JavaScript, forms, page network
↓
MonoSurf / kernel-cli websurf
↓
native dialog or browser chrome appears
↓
Kernel CLI
↓
return to the page and verify
```
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](/kernel-cli/commands) when the
browser workflow leaves the page surface.
## Companion Tools
| Tool | Owns | Choose it when |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| MonoSurf or `kernel-cli websurf` | Interactive Chromium page, shared `lib-monosurf` facade and `lib-monosurf-core`, CDP, profiles, site actions | The page uses JavaScript, login state, interaction, or browser-level evidence |
| [Kernel CLI OS commands](/kernel-cli) | Native OS, browser chrome, dialogs, apps, accessibility, input | The workflow crosses outside the page |
| MonoFetch | Direct HTTP-to-content conversion | A public resource does not need a browser or interaction |
| [Monolex CLI / Agent Browser](/ai-clis/monolex-cli) | Visible managed browser and same-profile login handoff | Cookies plus localStorage, IndexedDB, service workers, and passkey state must stay together |
| [OpenCLIs Vault](/ai-clis/openclis-vault) | Stable encrypted token and cookie-snapshot backend | MonoSurf needs protected snapshot storage without exposing values in profile metadata |
| [MonoPass](/ai-clis/monopass) | Passkeys and WebAuthn/FIDO2 ceremonies | A workflow needs structured passkey state rather than browser cookies or generic tokens |
| Monomento | Searchable knowledge index | Collected content must become retrievable memory |
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
Learn every supported command family, connection mode, option group, and
safety boundary in MonoSurf 0.11.3.
See how installed domains expose reusable read and write commands.
Understand read/write grants and protected browser-session access.
Continue a workflow through native dialogs, browser chrome, or another
desktop application.