Co-browse architecture deep dive: live presence, sessions and tokens, rrweb, file proxy, and watchdogs
How Co-browse works under the hood: live presence, the session lifecycle and one-shot tokens, rrweb capture, the file proxy, and the watchdogs that close stale sessions.
Watch this step in the video · Privacy and good practices
This article is for admins and technical teams who want to understand how Co-browse works internally: the moving parts involved when an agent watches a customer's screen live, how each session is authorized, and what stops a session from hanging open. You don't need any of this for everyday use (see the getting-started articles linked below for that), but it will help you troubleshoot and trust the data isolation.
Requirements
- The Co-browse add-on active on your plan (enforced by
CobrowseGate). - The Omnifox widget installed on the customer's site.
- Inbox permissions for the agent starting the session.
The pieces and how they fit
- Live presence. While the customer has the widget loaded, Omnifox knows they are "present" on a page. That signal is what enables the Co-browse button in the chat header (ChatHeader). No live presence, no screen to request.
- Session request. The agent clicks Co-browse and a
cobrowse.session.requestedevent is emitted over the widget channel. The widget lazy-loads the capture bundle only when that event arrives, so sites that never use it pay no weight. - Session + token. The backend creates a Co-browse session in the tenant database, guards concurrency with Redis, and issues a one-shot client token. That token authenticates the widget against the private
private-cobrowse.{id}channel on Reverb; once used, it can't be reused. - rrweb capture. The widget uses rrweb to record the DOM and page mutations and streams them as
eventWithTimeevents. On the agent side, the CobrowseSession modal replays them with rrweb'sReplayerinliveMode. - Agent actions. The agent's clicks, scrolls, and typing are translated into xpath references and sent back to the customer, without exposing the workspace bus (channel is per-session, not per-workspace).
- File proxy. If the customer page loads PDFs or private documents from S3, Omnifox serves them through
/file-proxy(same-origin) to avoid CORS issues, just like/img-proxydoes for images. - Watchdogs. Scheduled tasks that run every minute close sessions on timeout or when they go stale (no activity), releasing the Redis concurrency slot. So a tab closed abruptly never leaves a session "alive" forever.
Verification
- Start a test session with the [email protected] org and confirm you see the customer's DOM in the modal.
- Check that the channel in use is
private-cobrowse.{id}(not a workspace channel). - Close the customer's tab and confirm the session shows as closed within ~2 minutes.
If it doesn't work
- No Co-browse button: verify the add-on is active on the plan (
CobrowseGate) and the customer has live presence. - Widget won't join the channel: usually the one-shot token was already consumed (re-issue the request) or Reverb is down.
- Widget shows an old version after a deploy: Cloudflare caches
/widget/*. Purge theomnifox.iozone after deployingcobrowse.js. - PDFs or images won't load: make sure they go through
/file-proxyand/img-proxy; a direct S3 asset will fail on CORS.
Tips
- The client bundle lives separately (
public/widget/cobrowse.js) and is built with its own Vite config; don't mix it with the app build. - Co-browse in production is authoritative: pull before editing cobrowse files, and never blindly sync dev→prod.
Related articles
Related articles
-
What Co-browse is and how to enable it
Co-browse lets you see the customer's screen in real time to guide them better. Learn how to enable it.
-
Co-browse complete guide
Co-browse in depth, in 32 chapters: radar, identified visitors, consent, remote control, masking, marks, voice call, page changes and how a session ends, all real.
-
Co-browse: add-on tiers and pricing
Co-browse is bought separately on any plan: Standard 50 USD/mo (3 concurrent sessions), Pro 90 (6), Business 150 (10) and custom Enterprise.
-
How to start a Co-browse session with a customer
Step by step to invite the customer to share their screen and guide them in real time.
-
Prerequisites for using Co-browse
Before you start your first Co-browse session, check the add-on, your permissions and the Webchat channel conditions.