Browser Profile Attachment

Contract, lifetimes, refusals, and platform scope for attaching Cua Driver to an existing Chromium profile.

Existing-profile attachment is an additive browser_prepare strategy. It does not change the lifecycle of driver-owned isolated_new and isolated_named profiles.

Request#

{
  "pid": 844,
  "window_id": 10725,
  "session": "research-1",
  "strategy": { "kind": "existing_profile" },
}

pid, window_id, and session are required. strategy cannot be combined with legacy allow_launch or profile fields. Authorization depends on the runtime's immutable permission mode:

standard requires either the trusted launch option --grant existing-profile or an authorization callback supplied by the embedding application.
bounded requires the approved manifest to match the browser profile, application identity, and requested operation.
unrestricted attaches without a second authorization after the trusted launcher supplied --dangerously-bypass-approvals.

Cua Driver does not display its own confirmation modal or persistent banner. The CLI launch grant is useful when a person or trusted supervisor starts the runtime. Embedded applications can collect authorization in their own UI and return the decision through DriverAuthorizationHost.

The ordinary MCP destructive-tool marker does not authorize this strategy. It proves transport provenance, not approval to use an authenticated browser profile. A standalone standard-mode runtime without a launch grant or host callback fails closed.

Success result#

A successful call returns action: "attached_existing_profile" and an attachment object with:

Field	Value
`kind`	`existing_profile`
`browser`	`chromium`
`capabilities_invalidated`	`true`
`next_action`	`get_browser_state`

side_effects reports the bounded setup and browser-owned connection effects:

Field	Meaning
`opened_setup_page`	A temporary tab was opened in the approved native window.
`closed_setup_page`	That temporary setup tab was closed successfully.
`focused_setup_address_field`	The temporary tab's address field received in-app focus for exact navigation.
`enabled_remote_debugging`	The exact per-instance Chrome checkbox was toggled from off to on and the same control's resulting state was verified.
`used_bounded_pixel_fallback`	macOS used its setup-page-only pixel route to read or change the checkbox after the web AX subtree was unavailable.
`foregrounded_window`	Setup temporarily foregrounded the exact approved browser window for a bounded local action.
`injected_global_input`	Setup delivered global mouse or keyboard input only after revalidating the approved browser process and window.
`changed_preferences`	Mirrors `enabled_remote_debugging` for the generic prepare contract.
`displayed_consent_prompt`	Chrome displayed its browser-owned connection prompt.

All fields are false when the endpoint was already available. The driver does not return the profile identity, endpoint address, port, connection generation, grant identifier, or internal authorization details.

A refusal after setup begins may include detail.setup_side_effects. This uses the same setup fields and adds restored_remote_debugging when the driver had to reverse its own checkbox change. It never claims cleanup succeeded unless the exact checkbox returned to the off state.

On macOS, Cua Driver prefers the checkbox's semantic AX action. Current Chrome versions can withhold the internal page's web AX subtree even while exposing the native address field and selected setup tab. The bounded fallback runs only in the temporary tab Cua Driver created and navigated, after the fixed internal URL is committed, the expected title is selected, and no omnibox edit is in progress. It requires one unique checkbox-shaped control in the setup-page region, revalidates the unchanged window, sends the click only to the approved browser PID, and verifies the visual state change. That bounded global-input route may briefly foreground the exact approved window and then restores the previous frontmost app; foregrounded_window and injected_global_input report what occurred. Unsupported appearance, scale, zoom, window-size, or browser-toolbar geometry—including layouts shifted by a bookmarks bar—is refused without a click. It is not available for ordinary web content.

On refusal, restored_remote_debugging: true means the exact semantic checkbox, or the setup page's sole bounded pixel checkbox when web AX became unavailable, was proven off during cleanup. A false value means cleanup could not prove the state; callers must not infer that remote debugging is disabled.

Grant lifetime#

The grant is scoped to the runtime instance, public session, transport session, browser process fingerprint, approved native window, and proven loopback endpoint. It expires after 30 minutes of inactivity or eight hours absolutely, whichever comes first. Session end, browser prompt dismissal, identity mismatch, reconnect exhaustion, and runtime shutdown revoke it.

One browser-level connection is owned per generation. At most three reconnect attempts are made after a socket loss. A successful reconnect increments the generation and invalidates every target, tab, snapshot, frame, and ref minted by the previous generation.

Security properties#

Property	Guarantee
Network exposure	The accepted DevTools endpoint must be loopback-only.
Process binding	The endpoint, native window, and live process fingerprint must agree before every mutation.
Driver authorization	Standard requires a trusted launch grant or host callback. Bounded requires a matching approved manifest. A model-supplied Boolean and ordinary MCP approval are insufficient.
Revocation	`cua-driver revoke`, session end, browser identity changes, expiry, and runtime shutdown revoke the attachment grant.
Capability scope	Targets, tabs, dialogs, frames, and refs are opaque, session-scoped, and invalidated after navigation or connection-generation changes.
Profile handling	Cua Driver does not copy, edit, restart, or terminate the selected existing profile.
Residual local risk	CDP itself is not authenticated. Another process running as the same OS user may connect to an exposed endpoint outside Cua Driver. Cua Driver is a same-user tool boundary, not a defense against a hostile process with the same OS account.

An isolated profile is the recommended default. Existing-profile attachment is appropriate only when the task requires its authenticated state and the host is trusted. See Browser targeting and background delivery for why Cua Driver uses CDP and which risks remain outside the driver.

Refusals#

Code	Meaning
`browser_consent_required`	Standard has no launch grant or host decision, or bounded has no matching manifest grant.
`browser_consent_revoked`	The host denied the request or the browser-owned connection prompt was dismissed.
`browser_requires_setup`	No unique approved browser endpoint is available.
`browser_endpoint_owner_mismatch`	Endpoint ownership or identity changed.
`browser_wrong_target_refused`	The native window, prompt, or browser target is not exact.
`browser_binding_stale`	A connection generation changed; bind again.
`browser_reconnect_exhausted`	The bounded reconnect policy could not establish a proven socket.
`browser_input_incomplete`	Keystroke typing delivered only a reported prefix.
`browser_route_unavailable`	The classified engine or platform has no accepted typed route. For Firefox and Safari, bounded detail identifies the required protocol and current lifecycle limitation.
`browser_input_trust_unavailable`	Trusted input cannot preserve background posture. Bounded detail identifies the explicit `dom_event` alternative when a synthetic ref-targeted action is acceptable.
`browser_origin_outside_scope`	A bounded-mode tab left the manifest's allowed origin set; further mutation pauses.

Recording and telemetry#

Host authorization events contain only bounded metadata and the structured outcome. They do not include browser screenshots or accessibility snapshots. Public results, recordings, and telemetry must not contain profile paths or hashes, endpoint URLs or ports, page content, tab URLs, cookies, or storage. The content-free browser operation and refusal fields are documented in Telemetry and privacy.

Platform scope#

The browser-setup route is implemented for Google Chrome and Microsoft Edge on macOS and Windows. Chrome and Edge have product-specific acceptance evidence on Linux X11. Chrome is also accepted on GNOME Wayland, and Chromium is accepted alongside Chrome and Edge on the validated native-Wayland Sway lane. The Chromium-family products use the same descriptor-backed Linux route, but still need product-specific acceptance evidence on each desktop before they are listed as validated. Every route requires an exact authorized PID and native window, one uniquely matched setup control, a loopback endpoint owned by that process, one exact browser-owned consent action, and a fresh native/CDP rebind.

Linux additionally requires the browser's complete AT-SPI renderer tree. Start the Chromium-family process with --force-renderer-accessibility, or run a screen reader that enables full renderer accessibility. On Sway and validated GNOME Shell sessions, Cua Driver briefly focuses the exact compositor-attested window for fixed internal-page navigation and restores the previous window before continuing. GNOME requires the maintained WinRects helper API v4 and an immutable D-Bus owner that resolves to the current user's system-installed GNOME Shell process. Cua Driver refuses generic Wayland sessions that cannot prove exact process, window, and geometry identity.

The setup adapters currently recognize the products' English accessibility labels. Other UI locales fail closed without toggling an unrecognized control. Safari, Firefox, Brave, Vivaldi, Opera, Arc, and Electron do not have an existing-profile setup descriptor and return a structured refusal. An already available endpoint may still use the ordinary exact browser binding route when the platform independently proves it.

See Drive a web page for the task workflow and Browser targeting and background delivery for the security and generation model.