Should the server’s agent browser be pluggable? Starting with a remote CDP endpoint

[codewarnab]

Make the server-side agent browser pluggable (remote CDP as a first step)

The problem

The browser the agent controls on the server is currently tied to the bundled chrome-headless-shell. That works well by default, but it's hard to use in a few setups:

• Locked-down CI, network-restricted servers, or NixOS, where downloading and executing the bundled binary isn't possible
• Linux hosts where the sandboxing/AppArmor setup is a pain
• Reusing an already-running Chrome to save RAM
• Routing traffic through a residential proxy or anti-detect browser that speaks CDP [ eg camofox]

The Electron desktop mode already uses connectOverCDP(endpoint) in ServerBrowserContexts.ts, so the server clearly can work against an external browser. It just isn't reachable from headless/server deployments.

Smallest step I'd propose

A single env var, T3CODE_CDP_WS_ENDPOINT. When set, the server:

1. skips the PreviewBrowser download/verify/install step
2. calls chromium.connectOverCDP(endpoint) instead of chromium.launch(executable)

When unset, behaviour is unchanged, and the Electron path isn't touched. Both pieces already exist, so this is mostly wiring.

Where this could go

If this direction is OK, the same idea could grow into a small "browser provider" notion:

Mode	Description
bundled (default)	today's chrome-headless-shell
executable	launch a user-supplied Chrome/Chromium path
cdp	attach to a remote endpoint (this proposal)

That would make the browser configurable and runnable anywhere (a sidecar container, a remote machine, a hosted browser service) without forks.

Questions I'd love input on

1. Env var vs. config: is an env var the right surface, or should this live in server settings with the env var as an override?
2. Context ownership: on attach, should we create a fresh browser context per session, or reuse the default one? Who closes what on shutdown, given we don't own the process?
3. Capabilities: the viewer needs Page.startScreencast. Standard --remote-debugging-port Chrome supports it, but should we detect and fail clearly when an endpoint doesn't?
4. Auth and security: a CDP endpoint is full browser control. Should we support endpoints that need headers or tokens, and document that it must never be exposed publicly?
5. Resilience: should a dropped connection reconnect, or surface an error to the session?

Alternatives considered

Keeping a local patch on top of ServerBrowserContexts.ts / PreviewBrowser.ts works, but it needs a manual rebase on every upstream change to those files.

Happy to put up a PR for the env-var step if the direction sounds right.

[codewarnab]

@juliusmarminge