This feature ships in public desktop 0.5.7. The resident exposes target-loopback, per-tab and browser-level CDP WebSockets through the existing Chrome extension. Commands and events use ordinary CDP JSON. No browser debug port or UAC helper is required.
Set up the extension in Permissions, load it in Chrome, and enable
Browser scripts and DevTools. Keep a live owner with devtools scope open
for the entire WebSocket session. Include browser scope when using ordinary
tab discovery or navigation through that owner.
Request {"operation":"browser.endpoint"} through the Python SDK's retained
ControlSession.call or the JSON-lines control stream command:
machine-control --target TARGET --claim CLAIM control stream \
--reason "Inspect browser events" --scope browser --scope devtools
Send the endpoint request on stdin and leave that stream open. The result's
data.devtoolsEndpoint is a template:
ws://127.0.0.1:PORT/devtools/page/<tabId>?token=TOKEN
Replace <tabId> with the numeric ID from browser.tabs. Connect a tab-level
CDP client that omits the Origin header. Send, for example:
{"id":1,"method":"Runtime.enable","params":{}}
{"id":2,"method":"Runtime.evaluate","params":{"expression":"document.title","returnByValue":true}}Replies have id and result or error; streamed events have method and
params. Subscription lifetime belongs to that connection. A one-shot CLI
browser endpoint returns retained_owner_required when the resident requires
ownership, because ending the command would immediately invalidate its URL.
The same response's data.browserEndpoint addresses the browser facade:
ws://127.0.0.1:PORT/devtools/browser?token=TOKEN
Keep the same owner alive while connecting a browser client. With Playwright
1.63, use chromium.connectOverCDP(browserEndpoint, { noDefaults: true }) to
preserve the current profile's browser defaults, including download policy.
Use browser.contexts()[0] for existing tabs or context.newPage(); creating
an isolated context refuses. Puppeteer 25.12 uses
puppeteer.connect({ browserWSEndpoint: browserEndpoint, defaultViewport: null }).
Disconnect the client when finished. The facade refuses Browser.close.
Browser discovery exposes supported default-profile pages, omitting incognito,
privileged Chrome pages and the Web Store. Root methods support version/context
observations, target discovery, flattened attachment, new tabs, activation and
close. A logical mc-default context identifies the current profile; it does
not provide storage isolation. Synthetic tab wrappers support clients that
attach tabs before their pages. Related native iframe/worker sessions receive
connection-local IDs, preserved on commands, results and events. Unknown or
detached IDs refuse. A root connection excludes raw per-tab connections, and
at most 256 attached routes are retained.
Root auto-attachment cannot pause a newly created renderer before its first
script runs: facade page/tab attachments report waitingForDebugger: false.
Native child auto-attachment preserves Chrome's actual waiting flag. Isolated
contexts, browser-wide downloads, shutdown and unavailable CDP domains return
protocol errors. This is a supported compatibility subset; client features
outside it must be qualified separately.
The address is loopback on the target, even for an outside caller. An outside client needs an authenticated forwarding tunnel to that target's ephemeral port while retaining the same owner. Preserve the target loopback Host header, for example by forwarding the same local port. The common facade does not automatically create a WebSocket tunnel. A copied URL cannot open or renew ownership. Treat its token as bearer access to the current owner's DevTools authority; do not save it in transcripts, logs or public evidence.
Browser-only access cannot create an endpoint. Pause, Stop, expiry, lock/session loss, owner disconnect, failed audit storage and provider-generation changes close streams and invalidate old tokens. Resume or provider reconnect requires a newly issued endpoint, and a new owner when ownership ended. The bridge checks authority before commands and before forwarding replies/events.
The listener accepts only strict upgrades on IPv4 loopback and refuses every
Origin header, including an empty one. It bounds the handshake to 8 KiB and
five seconds, connections to eight, and each tab to one raw connection. Commands
are text objects with a unique outstanding nonnegative 32-bit integer id, a
Domain.method, optional object params and optional bounded sessionId.
Client frames are bounded below 1 MiB; native framing overhead
also counts against its 1 MiB limit. At most 16 commands may be outstanding.
Completion has a 45-second deadline. Output queues hold at most 64 frames and 16 MiB in total; a blocked send has a three-second deadline. Malformed frames, duplicate IDs, exceeded bounds, slow consumers and uncertain completion close the connection. Commands are never replayed automatically.
Native detach cleanup can finish shortly after socket closure. A connection attempt to that tab may be refused until the bounded cleanup completes. Wait for cleanup before reconnecting; never replay uncertain CDP commands.
Raw CDP replies establish provider delivery, not an independently observed website effect. Check important effects separately. Audit history stores typed operation, generation, hashed correlation and outcome metadata, excluding URLs, tokens, CDP methods, parameters, page data and events. Same-user shell access is not contained. Chrome's debugger indicator remains visible, and Chrome may refuse restricted tabs or CDP domains.
Tactical 099 owns focused VM per-tab evidence. Tactical 100 owns browser-client qualification. Signed-release, ARM64 and physical qualification remain separate.