Four Ways to Drive the Same Engine
Obscura exposes four main relationships with a page: a bounded command-line job, a CDP session for existing automation clients, a stateful MCP session for an AI agent, or a direct Rust embedding. This chapter explains how to choose among them based on control granularity, session continuity, language, rendering, and request observation. The key judgment is that these are adapters around one stateful engine, not four ways to escape its lifecycle, compatibility, or safety limits.
The right interface depends on who owns the workflow. A shell command may own one extraction and then exit. A Playwright program may own a long-lived browser session and expect protocol events. An agent needs compact observations and a reliable observe–act–observe loop. A Rust service may own the crawl itself and want callbacks without serializing every action through a remote protocol. The same page model can support all four, but the boundary at which the caller takes responsibility changes.
The interface is a relationship with page state
Start with the simplest case: a job that needs to fetch a set of URLs, evaluate a small expression, and write text, links, Markdown, assets, or raw response bodies. The CLI is a good fit because it makes the shell the workflow owner. It exposes navigation, waiting, evaluation, proxy and user-agent choices, optional stealth, and parallel scraping without requiring the caller to maintain a target/session graph.
That simplicity is a control choice, not evidence that the underlying engine is simple. The CLI still drives the same page lifecycle, JavaScript runtime, network policy, and optional renderer. A command that dumps text from an SPA may still need a settle policy. A command that captures a screenshot needs a render-enabled build. A command that fetches untrusted pages still inherits network and process boundaries. The CLI removes protocol-management work; it does not remove browser semantics.
A long-lived Node or Python automation program has a different relationship. It already speaks Puppeteer or Playwright, needs to create pages, evaluate functions, click, fill, listen for events, manage cookies, and perhaps capture screenshots or PDFs. Obscura’s CDP server lets such a client connect over WebSocket. Playwright must use connectOverCDP, because its private connect protocol is not the protocol Obscura implements. The value is compatibility with an existing programming model, not a claim that every Playwright feature is present.
An AI agent has a different problem again. The agent does not usually want to manage raw protocol identifiers for every action. It needs to inspect the current page, locate actionable elements, act, wait, and inspect again. MCP packages that relationship as a live browser session with snapshots, element references, interaction tools, tabs, extraction, diagnostics, cookies, storage, and optional visual output. The tool surface is higher-level, but it is not stateless: the active page, current document, and previous snapshot determine what the next action means.
A Rust service that embeds Obscura owns still more of the workflow. The library API gives it a Browser and Page surface for navigation, evaluation, selection, settling, cookies, and direct state access. It can register passive request and response callbacks, intercept requests to continue, fulfill, fail, or rewrite them, and install a preload script before page scripts run.