Sharing a singleton Chromium CDP service across multiple OpenCrabs profiles

[leshchenko1979]

The Problem

OpenCrabs compiles browser tools (browser_navigate, browser_click, etc.) into every profile binary via the browser feature. Each tool relies on a BrowserManager struct that calls chromiumoxide's Browser::launch() to spawn a headless Chromium instance directly over CDP — no intermediate scripts, no shared state. The struct is not a singleton: every profile carries its own BrowserManager, and every ensure_browser() call spawns a fresh Chromium process on its own random debugging port (--remote-debugging-port=0).

With 3 profiles (default, ops, family), any browser action triggered independent Chromium instances. A real measurement of the built-in tools on a 961 MB VDS showed:

• 11 Chrome processes for a single profile
• ~500 MB RSS during active browsing
• 3 × 500 MB ≈ 1.5 GB if all 3 profiles are active — instant OOM on a 961 MB VDS

No shared lifecycle, no crash recovery, no logging — each profile managed its own browser independently, with no coordination mechanism.

The Solution

A singleton Chromium service shared across all 3 profiles, controlled by a lightweight Python bridge (/usr/local/bin/cdp-bridge).

Architecture

Profile A ──┐
Profile B ──┼── cdp-bridge ──→ chromium-cdp.service (singleton)
Profile C ──┘

• chromium-cdp.service — systemd unit running one headless Chromium with CDP on port 9222
• cdp-bridge — Python script that checks the service is alive via systemctl show and provides a clean WS interface for CDP commands
• Each profile connects to the bridge instead of spawning its own Chromium

Chromium flags used

--headless=new --disable-gpu --no-sandbox
--remote-debugging-port=9222 --disable-dev-shm-usage
--disable-extensions --renderer-process-limit=1
--js-flags=--max_old_space_size=256

Key flag: --renderer-process-limit=1 limits to one renderer process. (Memory-heavy --single-process was unstable — crashed with SIGTRAP on this kernel.)

Why not chromiumoxide?

We could have patched chromiumoxide to use a shared port, but:

• Each profile's Browser::launch() starts its own process — the Cargo feature browser embeds the full launch logic per binary
• A shared port doesn't prevent duplicated browser processes (each profile still spawns its own)
• A singleton service is simpler, OS-managed (systemd), and works with any profile without code changes

systemd hardening

Memory limits and crash protection added to chromium-cdp.service:

Setting	Value
MemoryMax	400M
MemoryHigh	300M
Restart	always
StartLimitBurst	5 / 30s
NoNewPrivileges	yes
PrivateTmp	yes
ProtectSystem	strict

Profile services

All 3 profiles (default, ops, family) run as user-level systemd units with Wants=chromium-cdp.service and After=chromium-cdp.service — ensuring the Chromium singleton starts before any profile that needs it.

Results

A full browsing session on rede-vest.ru (scrolling top to bottom, loading all content) was measured step by step:

cdp-bridge singleton (shared across 3 profiles):

Step	Chrome RSS
Idle (service just started)	259 MB
Page loaded	322 MB
Full scroll-through	326 MB
Scrolled back to top	325 MB

• Service memory stable at ~260 MB idle, ~325 MB peak
• No OOM. 375 MB free on a 961 MB VDS.
• No socket conflicts — single port 9222, single process, all profiles share it.
• Systemd handles restarts — if Chromium crashes, it's back in 5 seconds.

Takeaways

1. A singleton browser is simpler, cheaper, and more reliable than per-profile instances
2. --renderer-process-limit=1 cuts memory ~40% without breaking page rendering
3. systemd hardening (MemoryMax, NoNewPrivileges, ProtectSystem) prevents resource leaks and OOM
4. A lightweight Python bridge is enough — no need to embed CDP logic per binary

[leshchenko1979]

@adolfousier maybe you would want to make the cdp-bridge a built-in solution.

[adolfousier]

Done. Added browser.cdp_endpoint config option in commit 22cce2d9.

When set, the browser manager connects to an existing Chromium instance via CDP instead of spawning a new one. All profiles can share a single browser.

Usage:

1. Start a standalone Chromium with CDP enabled:

chromium --remote-debugging-port=9222 --headless --no-sandbox

2. Add to each profile's config.toml:

[browser]
cdp_endpoint = "ws://localhost:9222"

Results:

• Memory: ~260MB (single instance) vs ~750MB (3 profiles × 250MB)
• No Python bridge needed
• No systemd service required
• No external dependencies

The browser manager now checks for cdp_endpoint first. If set, it connects via Browser::connect(). Otherwise, it falls back to launching a new browser as before.

Test added: cdp_endpoint_connects_to_existing_browser (ignored by default, requires external Chromium).

3783 tests pass, clippy clean.

[leshchenko1979]

That was fast!!!! :)))

Thanks! :)

This memory saving feature compounds with the whole Opencrabs promise of a tiny memory footprint.