Browser Setup (No-Root Linux)

Install and configure headless Chrome for OpenClaw browser tool in environments without root/sudo access (cloud containers, VPS, sandboxed hosts). Use when:...

Security Scan

The skill's files and instructions are consistent with its stated purpose (installing Chrome in a no-root Linux environment); it downloads Chrome and supporting .deb packages into the user's home, creates a wrapper, and does not request credentials or system-wide privileged changes.

Purpose & Capability

The name/description match the actual behavior: the SKILL.md and script download Google Chrome, extract .deb packages, copy shared libraries and fonts into ~/local-libs and ~/.fonts, and create a wrapper. None of the required resources (no env vars, no external credentials) are unexpected for this task.

Instruction Scope

The SKILL.md instructs the agent to run the included install script and to start Chrome with --remote-debugging-port and --no-sandbox. These are expected for unprivileged container usage, but --no-sandbox reduces process isolation and remote-debugging opens a CDP port that could be exposed if the host/container network is misconfigured. The instructions reference only user-home paths and OpenClaw config files; they do not request unrelated system credentials or hidden data exfiltration.

Install Mechanism

This is an instruction-only skill with a shipped script. The script downloads Chrome from the official dl.google.com URL and uses apt-get download to fetch dependency .debs, then extracts them into user directories using dpkg-deb -x. This approach is coherent for no-root installs. Note: apt-get download uses the system's configured APT sources (mirror integrity depends on the system's apt configuration).

Credentials

No credentials, secrets, or system config paths are requested. The script writes files to the user's HOME only (~/chrome-install, ~/local-libs, ~/.fonts, ~/.config/fontconfig), which is proportionate to the task.

Persistence & Privilege

The skill does not request permanent platform privileges or always:true. It creates files under the invoking user's home and a wrapper script; this is expected for a local install tool and does not modify other skills or global agent settings.

Assessment

This skill appears to do what it says: extract Chrome and supporting libraries into your home and create a wrapper for headless use. Before running it: (1) inspect the script yourself (it is included) and run it in a safe/test environment first; (2) be aware the wrapper/usage recommends --no-sandbox (necessary without root but weakens isolation) and starts Chrome with remote debugging — ensure the debugging port is not exposed to untrusted networks; (3) apt-get download will fetch .debs from your system's APT sources, so verify your apt sources are trusted; (4) if you need stronger assurance, replace the dl.google.com download with a pinned checksum or a signed release you verify, and run the script under a user account/container without sensitive data.

Install headless Google Chrome for OpenClaw's browser tool on Linux without root access.

When to Use

• browser start fails with "No supported browser found"
• Chrome starts but pages crash ("Page crashed", "Target page closed")
• Running on a cloud container, VPS, or sandboxed environment without sudo

Quick Start

bash scripts/install-browser.sh

The script downloads Chrome, extracts ~40 shared library packages, installs Liberation fonts, creates a wrapper script, and verifies the installation. Takes ~2 minutes.

Then configure OpenClaw:

openclaw config set browser.executablePath "$HOME/local-libs/chrome-wrapper.sh"
openclaw config set browser.headless true
openclaw config set browser.noSandbox true
openclaw config set browser.attachOnly true

Set the CDP port for the openclaw profile (edit ~/data/openclaw.json or equivalent config):

{
  "browser": {
    "executablePath": "~/local-libs/chrome-wrapper.sh",
    "headless": true,
    "noSandbox": true,
    "attachOnly": true,
    "profiles": {
      "openclaw": { "cdpPort": 18800, "color": "#FF4500" }
    }
  }
}

Critical: attachOnly Must Be true

OpenClaw has two internal paths for browser operations:

• CDP path (start/stop/tabs): communicates directly with Chrome's CDP port
• Playwright path (navigate/snapshot/act): uses playwright-core bundled with OpenClaw

When attachOnly: false, Playwright calls launchOpenClawChrome() which checks ensurePortAvailable(cdpPort). Since Chrome is already listening on that port, it throws PortInUseError on every navigate/snapshot/act call.

When attachOnly: true, Playwright uses connectOverCDP() to attach to the running Chrome instance. No port conflict.

Always set attachOnly: true when using a wrapper script or manually-started Chrome.

Usage Flow

Starting Chrome

Chrome must be started before OpenClaw can use it. Start it manually:

~/local-libs/chrome-wrapper.sh \
  --headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage \
  --remote-debugging-port=18800 \
  --user-data-dir=~/data/browser/openclaw/user-data \
  --no-first-run --disable-setuid-sandbox \
  about:blank &

Or let OpenClaw start it (if attachOnly: false — but this causes PortInUseError on Playwright operations, so not recommended).

Browser Tool Flow

browser start (profile=openclaw)   → detects running Chrome via CDP
browser navigate (targetUrl)       → Playwright connectOverCDP → loads page
browser snapshot                   → accessibility tree (structured page data)
browser screenshot                 → PNG capture
browser act (ref=e12, kind=click)  → interact via ref from snapshot

Common Issues

Missing Shared Libraries

Symptom: error while loading shared libraries: libXXX.so: cannot open shared object file

Fix: The install script handles this. If new libraries are missing after a Chrome update, check with:

LD_LIBRARY_PATH=~/local-libs/lib ldd ~/chrome-install/opt/google/chrome/chrome | grep "not found"

Then apt-get download <package>, extract with dpkg-deb -x, copy .so files to ~/local-libs/lib/.

Page Crashed

Symptom: page.goto: Page crashed or Target page, context or browser has been closed

Cause: Missing fonts. Chrome's renderer crashes when no fonts are available.

Fix: Install fonts (the script does this). Verify ~/.fonts/ has .ttf files and ~/.config/fontconfig/fonts.conf exists. The wrapper script must export FONTCONFIG_FILE.

PortInUseError

Symptom: PortInUseError: Port 18800 is already in use

Cause: attachOnly is false — Playwright tries to launch a new Chrome on the same port.

Fix: Set browser.attachOnly: true in OpenClaw config.

CDP Timeout / Backlog

Symptom: browser start succeeds but subsequent calls timeout.

Cause: Failed Playwright connections accumulate in Chrome's TCP listen backlog (CLOSE-WAIT state), blocking new connections.

Fix: Kill Chrome (pkill -9 -f chrome), wait a few seconds, restart cleanly.

Small /dev/shm

Symptom: Renderer crashes on complex pages in containers.

Cause: Default container /dev/shm is 64MB, too small for Chrome.

Fix: --disable-dev-shm-usage flag (included in the wrapper). For Docker, also add --shm-size=256m to the container.

What the Install Script Does

1. Downloads Google Chrome stable .deb from Google
2. Extracts Chrome binary to ~/chrome-install/ using dpkg-deb -x (no root needed)
3. Identifies missing shared libraries via ldd
4. Downloads ~40 library .deb packages via apt-get download (no root needed)
5. Extracts all .so files to ~/local-libs/lib/
6. Downloads fonts-liberation and installs .ttf files to ~/.fonts/
7. Creates fontconfig config mapping sans-serif/serif/monospace → Liberation fonts
8. Creates ~/local-libs/chrome-wrapper.sh that sets LD_LIBRARY_PATH + FONTCONFIG_FILE
9. Verifies Chrome can start and report its version

Package List Reference

Libraries downloaded (Ubuntu/Debian names, may vary by distro):

libglib2.0, libnss3, libnspr4, libatk1.0, libatk-bridge2.0, libcups2, libdrm2, libxkbcommon0, libxcomposite1, libxdamage1, libxfixes3, libxrandr2, libgbm1, libasound2, libatspi2.0, libdbus-1-3, libxcb1, libx11-6, libxext6, libcairo2, libpango-1.0, libpangocairo-1.0, libffi8, libpcre2-8-0, libxau6, libxdmcp6, libxi6, libxrender1, libpng16-16, libfontconfig1, libfreetype6, libxcb-render0, libxcb-shm0, libpixman-1-0, libfribidi0, libthai0, libharfbuzz0b, libavahi-common3, libavahi-client3, libdatrie1, libgraphite2-3