diff --git a/docker-compose.lightpanda.yml b/docker-compose.lightpanda.yml new file mode 100644 index 00000000..ccbb2147 --- /dev/null +++ b/docker-compose.lightpanda.yml @@ -0,0 +1,38 @@ +# Lightpanda sidecar overlay — lightweight CDP browser. +# +# Usage: +# docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.lightpanda.yml up -d --build +# +# Lightpanda (https://lightpanda.io) is a low-memory headless browser with CDP +# support. Opt-in alternative to the Chrome sidecar (docker-compose.browser.yml). +# See docs/browser-backends.md for the compatibility matrix. + +services: + lightpanda: + # Official Lightpanda CDP image: https://hub.docker.com/r/lightpanda/browser + image: lightpanda/browser:latest + ports: + - "127.0.0.1:${LIGHTPANDA_CDP_PORT:-9222}:9222" + healthcheck: + # Minimal TCP probe via sh's /dev/tcp. If the image is scratch-based + # without a shell, drop healthcheck and change depends_on below to + # `condition: service_started`. + test: ["CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/9222 || exit 1"] + interval: 5s + timeout: 3s + retries: 5 + deploy: + resources: + limits: + # Lightpanda is ~10x lighter than Chrome. + memory: 512M + cpus: '1.0' + restart: unless-stopped + + goclaw: + environment: + - GOCLAW_BROWSER_REMOTE_URL=ws://lightpanda:9222 + - GOCLAW_BROWSER_BACKEND=lightpanda + depends_on: + lightpanda: + condition: service_healthy diff --git a/docs/browser-backends.md b/docs/browser-backends.md new file mode 100644 index 00000000..d8d3f2f6 --- /dev/null +++ b/docs/browser-backends.md @@ -0,0 +1,57 @@ +# Browser Backends + +Goclaw's browser automation tool (`pkg/browser/`) connects to any CDP-compatible browser. Two backends are supported: + +| Backend | Image | Overlay | Status | +|---|---|---|---| +| **Chrome** (default) | `chromedp/headless-shell:latest` | `docker-compose.browser.yml` | Stable | +| **Lightpanda** | `lightpanda/browser:latest` | `docker-compose.lightpanda.yml` | Experimental | + +## Switching backends + +Both overlays set `GOCLAW_BROWSER_REMOTE_URL` to their respective sidecar. Only one should be active at a time. + +```bash +# Chrome (default) +docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.browser.yml up -d + +# Lightpanda +docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.lightpanda.yml up -d +``` + +Set `GOCLAW_BROWSER_BACKEND=chrome|lightpanda` to pick the backend explicitly. If unset, goclaw probes `/json/version` on the remote and auto-detects from the `Browser` field. + +## Compatibility matrix + +| Feature | Chrome | Lightpanda | Notes | +|---|---|---|---| +| Navigate / reload | ✅ | ✅ | | +| AX snapshot (`Accessibility.getFullAXTree`) | ✅ | ✅ | Primary "see the page" path for the agent | +| Click / type / hover / press | ✅ | ✅ | | +| Wait (text / URL / stable) | ✅ | ✅ | | +| Evaluate JS | ✅ | ✅ | Subset on Lightpanda — see upstream docs | +| Screenshot (`Page.captureScreenshot`) | ✅ | ❌ | Lightpanda returns a placeholder image. The tool returns an error on Lightpanda directing the agent to use `snapshot` instead | +| Multiple tabs per connection | ✅ | ❌ | Lightpanda: 1 CDP connection = 1 tab. Goclaw opens a fresh connection per tab transparently | +| Browser contexts / incognito | ✅ | Implicit | On Lightpanda every connection is already a fresh browser — isolation is automatic, no `Target.createBrowserContext` multiplexing | +| Cookies / localStorage shared across tabs | ✅ within a context | ❌ | Lightpanda: each tab is a fresh browser. A login on one tab is not visible to another | +| List open tabs from server | ✅ | ❌ | Lightpanda: no `/json/list`. Goclaw tracks tabs in its local map | +| Auto-reconnect on WS drop | ✅ | ❌ | Lightpanda: connection death = that tab is gone server-side. Goclaw drops the tab from the map and surfaces a clear error | + +## When to choose which + +**Lightpanda:** +- Memory-constrained deployments (desktop / Lite edition, small VPS). +- Stateless workflows — navigate, snapshot, extract, done. +- Cases where per-tab isolation is a feature (every tab is a fresh browser). + +**Chrome:** +- Multi-tab flows (OAuth popup → main window, tab-to-tab navigation). +- Long-lived sessions with shared login / cookies / localStorage. +- Screenshot-based workflows. +- Anything requiring full JS engine fidelity. + +## References + +- Lightpanda: https://lightpanda.io +- Lightpanda + go-rod demos: https://github.com/lightpanda-io/demo/tree/main/rod +- Tracking issue: https://github.com/nextlevelbuilder/goclaw/issues/223