When the Browser Becomes a Service: Hosts, Resources, and Trust

Camofox-browser stops being a local browser helper when more than one agent host, user identity, or deployment process can reach it. This chapter examines the service boundary that makes that sharing possible: the REST server, the standalone MCP adapter, the OpenClaw plugin, the common tool contract, and the controls around authentication, resources, files, traces, and telemetry. The practical outcome is a deployment judgment: readers should be able to identify which component owns a capability, which key or filesystem boundary protects it, and which browser-runtime costs remain even when the agent-facing adapter is small.

One contract, multiple doors

The REST server is the stable center because it owns the live browser. It launches Camoufox, creates user contexts and tabs, receives navigation and interaction requests, and shapes results for callers. An agent host does not need to know how the browser process is started or how a page is recovered; it needs a contract that says what request to make and what kind of result to expect.

Camofox-browser provides two different doors into that center. The standalone MCP package is a stdio process that an MCP-compatible host can start for a session. It forwards tool calls to an already-running REST server and does not itself pull in the browser engine, Playwright, or the large Camoufox binary. The OpenClaw plugin can also manage the REST server as a subprocess, wait for its health endpoint, and register browser tools. In both cases, the browser work remains on the REST side.

That division makes the adapter lightweight, but it does not make it unimportant. The MCP and OpenClaw paths use one canonical contract that defines the eleven tool names, their JSON Schemas, REST methods and paths, authentication classification, request bodies, screenshot decoding, snapshot response shaping, and cookie-import behavior. The adapters mainly differ in how they obtain the userId and session key that identify the browser state. A host can therefore change without silently changing the meaning of an agent's request.

The distinction between tool equivalence and browser equivalence is worth keeping. The repository's mock-HTTP contract tests assert that both host paths use the same wire-level behavior for the covered tools. They check route shapes, request bodies, bearer headers, screenshot decoding, error handling, and the fact that cookie import sends parsed cookies rather than a file path. That is strong evidence about the adapter boundary. It is not evidence that a live website will respond identically in every environment, that a host will display results in the same way, or that an action will have the same outcome after a page changes.

The common contract also reduces a particular class of security mistake. If one adapter treated cookie import as a path sent to the server while another parsed the file locally, the two hosts would have different filesystem and trust behavior even though they appeared to offer the same tool. Centralizing request construction keeps the sensitive distinction visible: the cookie file is read under the host-side containment rules, then the REST route receives a constrained cookie array.

The user identity still comes from outside the shared tool definition. A standalone MCP process has a per-process user ID by default, while a host can provide an explicit one. The session key partitions tabs within that user. Those values are not cosmetic metadata. They determine which BrowserContext the REST server locates and therefore which cookies, storage, proxy assignment, and live tabs a request can reach. A host integration that loses or reuses them incorrectly can send a valid request to the wrong identity.

flowchart LR O["OpenClaw plugin"] --> T["Canonical tool contract"] M["Standalone MCP adapter"] --> T T --> R["Camofox REST server"] R --> A["Access-key gate"] A --> C["User BrowserContext"] C --> L["Resource limits and reapers"] C --> P["Persisted profile"] C --> X["Trace and telemetry egress"] R --> D["Camoufox runtime and display dependencies"]

The diagram shows why the REST server is a system boundary rather than just another component in a list. The two hosts converge before the browser state is selected. The access gate sits before the user context. The context is surrounded by resource policy, durable profile state, and diagnostic egress, while the shared server still depends on the Camoufox runtime and display stack. A smaller adapter does not remove the larger trust and resource surface behind it.

This architecture also offers a deployment choice. If a REST server is already running on a local or remote machine, an operator can install only the MCP adapter.