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.

Jun 26, 2026

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

  1. 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.
  2. Session request. The agent clicks Co-browse and a cobrowse.session.requested event 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.
  3. 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.
  4. rrweb capture. The widget uses rrweb to record the DOM and page mutations and streams them as eventWithTime events. On the agent side, the CobrowseSession modal replays them with rrweb's Replayer in liveMode.
  5. 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).
  6. 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-proxy does for images.
  7. 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 the omnifox.io zone after deploying cobrowse.js.
  • PDFs or images won't load: make sure they go through /file-proxy and /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

Was this helpful?

Related articles

Message us on WhatsApp