Browser VM Setup

Browser Agent on a VM — Provisioning, Xvfb, Egress Cost Tiers

Stops at every defence: CAPTCHA / bot challenge / MFA / geo-gate / rate limit / block page → human hand-off, no evasion guidance. What this skill does instead: make a Linux VM actually run a headed browser, keep the admin shell off the internet, and stop the egress bill from running away.

Before you start — access, data, network

Only drive accounts and data you own or are authorised to access. The target's ToS and applicable law (GDPR when personal data is involved: legal basis, minimisation, stated retention) are constraints on this procedure, not footnotes. If you cannot name the legal basis, do not run the job.

When to Use

1. Host decision

Decide on this line, not on price: if the agent only touches open APIs and your own tools → VM, always. A target that default-denies datacenter ranges is not a host-sizing problem — the run stops there and a human rules on it (§5). A residential box is no free pass either: one home IP hammering a platform gets rate-limited on volume, no ASN required (§6).

2. Headless vs headed + virtual screen

On Linux with no DISPLAY, the browser tool falls back to headless automatically — no error, no warning. Check echo $DISPLAY before blaming the config.

sudo apt-get install -y xvfb x11vnc
Xvfb :99 -screen 0 1920x1080x24 &   # `&` dies at logout — systemd unit or xvfb-run for a daemon
export DISPLAY=:99

# Xvfb takes ~0.2-1 s to open its socket — polling avoids an intermittent
# "unable to open display" that looks like a broken install
until xdpyinfo -display :99 >/dev/null 2>&1; do sleep 0.2; done
xdpyinfo -display :99 | head -1
# Output: name of display:    :99

# Watch it live — from your laptop: ssh -L 5900:localhost:5900 user@vm → VNC to localhost:5900
x11vnc -storepasswd                 # writes ~/.vnc/passwd
x11vnc -display :99 -localhost -rfbauth ~/.vnc/passwd &

-localhost keeps it off the network; the SSH tunnel of §7 reaches it. It does not protect you from the machine: with -nopw, any local user or process on the VM can take the display — and the browser's logged-in sessions with it. Use -rfbauth, or accept -nopw only on a single-user throwaway VM.

Headed = compatibility mode. It renders through the real window/GPU path, so pages that break under headless (WebGL, video codecs, font metrics, layout-dependent widgets) usually just work. Cost: RAM/CPU per frame — enable on demand, not by default.

3. Provisioning traps

These four cost a day each, the first time.

# Chrome from .deb — never snap
wget -q https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt-get install -y ./google-chrome-stable_current_amd64.deb
google-chrome --version
# Output: Google Chrome 1XX.0.XXXX.XX

# Alternative: the runtime's own Chromium, already patched for CI
npx playwright install --with-deps chromium

Reference launch args for a VM: --no-sandbox --disable-dev-shm-usage --disable-gpu, headless: true (or false when DISPLAY=:99 is up). Registers, do not mix: noSandbox: true is the profile key in ~/.openclaw/config.json; --no-sandbox is the CLI flag it passes to the binary. Set one, not both.

4. Remote browser over CDP

Point the agent at a browser it does not own — it connects instead of spawning a local Chrome. Worth the network hop only for many isolated parallel sessions, or a browser that must live in its own container; one agent, one profile → local Chrome is simpler and free. In ~/.openclaw/config.json:

{ "browser": { "profiles": { "vm": { "cdpUrl": "ws://127.0.0.1:9222/devtools/browser/", "attachOnly": true, "noSandbox": true } } } }

Licence alert — non-obvious, and it bites at invoicing time. Some browser-as-a-service projects ship under SSPL: commercial use is not covered by the free licence, and some features are reserved for the paid plan rather than the free image. Check the licence and the plan of the product you pick before you architect on it, not after.

5. Egress cost tiers and their limits

The default egress is the VM's own IP, and this skill ships no other. The table below exists to budget a tier a human has already approved for a named target — it is not a ladder the agent climbs by itself.

attempt(url, egress=direct)
  → 200                                                → done, cost ~0
  → 403 / CAPTCHA / challenge / block page / geo-gate  → STOP, report, human hand.
                                                         No second attempt, no egress change.

GRAY-AREA — NOT RECOMMENDED, NEVER AUTOMATIC. Renting residential/ISP egress (billed per GB, the line item that runs away) after a datacenter-range 403 is documented here only so you recognise it and gate it. A default-deny on datacenter ASNs is an anti-abuse control; buying a consumer IP to turn its 403 into a 200 routes around that control. The agent must never do it on its own initiative, never as a retry, never as a default. It is a human decision, per target, before the run — and if any row below is unclear, the answer is no. A geo-gate states who the site serves; a challenge states it does not want an automated client. Both are answers, not errors.

6. Load & authorisation rules

Not tips — rules. They keep you inside published rate limits, inside the authorisation you actually have, and off someone else's servers' backs.

7. Hardening & access

The agent gateway is a prerequisite: install it from its vendor's own documentation before this section. This skill does not fetch or run an installer. Once it is up, it listens on 127.0.0.1:18789 by default and its dashboard executes shell. Treat it as a root console, because it is one.

# Bind loopback only — never 0.0.0.0
ss -ltnp | grep 18789
# Output: LISTEN 0 511 127.0.0.1:18789 ... users:(("node",pid=...))

# Reach it from your laptop
ssh -L 18789:localhost:18789 user@vm     # then open http://localhost:18789

A mesh network (e.g. Tailscale) is the same trade with less tunnel babysitting. Public exposure is not an option to weigh — it is an admin shell on the internet. Baseline around it: non-root user, UFW default-deny inbound, SSH keys only, secrets in a manager or a gitignored .env.

Why OAuth still completes through the tunnel: the dashboard opens in your laptop's browser at localhost:18789, so the provider's redirect back to localhost lands in the same browser that started the flow — nothing is exposed and the callback closes normally. Ship a public URL and you get the callback and the shell exposed at once.

8. GitOps — the VM is disposable

Everything is in the repo; the VM is a cache of it. Grill the VM → rebuild in ~10 min.

repo/
  provision.sh        # yours to write, idempotent: [ -x /usr/bin/google-chrome ] || install...
  deploy.sh           # git pull && restart daemon
  .env.example        # names only, never values
  .github/workflows/  # push main → ssh → ./deploy.sh
  openclaw/           # versioned ~/.openclaw config + SKILL.md files

provision.sh must be safe to re-run on a live box. Group your guards — A || B && C parses as (A || B) && C, so the "guarded" install runs anyway and can downgrade a working runtime mid-flight. And retention is executed, not declared: the purge cron below is what enforces the 7-day window announced above — install it, or do not announce a window.

if ! command -v node >/dev/null; then
  # Distro repo first. Newer major? NodeSource ships a setup script: download and read
  # it before running. Piping a remote script into sudo bash is the operator's call.
  sudo apt-get install -y nodejs
fi
node -v          # Output: v22.x.x

# Retention — screenshots and logs may hold personal data
mkdir -p ~/.openclaw/screenshots ~/.openclaw/logs   # find errors on a missing dir; cron then mails you nightly
( crontab -l 2>/dev/null | grep -q openclaw-purge ) || \
  ( crontab -l 2>/dev/null; \
    echo '17 4 * * * find "$HOME/.openclaw/screenshots" "$HOME/.openclaw/logs" -type f -mtime +7 -delete >/dev/null 2>&1  # openclaw-purge' \
  ) | crontab -

# Verify it landed, then prove it deletes: plant a file past the window, run the finder by hand
crontab -l | grep -c openclaw-purge          # Output: 1
touch -d '8 days ago' ~/.openclaw/logs/purge-probe.log
find "$HOME/.openclaw/logs" -type f -mtime +7 -delete
ls ~/.openclaw/logs/purge-probe.log
# Output: ls: cannot access '.../purge-probe.log': No such file or directory

Change the window in one place — the -mtime +7 of the crontab line — then re-run the verify; an unverified retention claim is a false claim. Snapshot before every risky change. Two schedule traps: keep unattended upgrades security-only — an unscheduled reboot mid-run loses the session; and some hosts require ID documents at signup, so budget a delay, not an afternoon.

Deploy checklist

Output Format

Emit this after every provisioning run — verbatim, one block, to your log or alert channel:

VM: [host/region] · [vCPU]/[RAM] · rebuilt-from: provision.sh@[commit]
BROWSER: [chrome-deb|playwright-chromium] [headless|headed:99] · shm=[size] · sandbox=[off|on]
EGRESS: [direct|other] · geo=[XX] · non-direct-approved-by=[human name|n-a]
ACCESS: dashboard=127.0.0.1:18789 via [ssh-tunnel|mesh] · public=no
DATA: persists=[cookies,screenshots,logs] · retention=[N days] · purge-cron=[verified|absent] · webhooks=[none|list]
CHECKS: display=[ok] · browser-launch=[ok] · heartbeat=[ok] · daemon=[ok]
BLOCKED: [none | target + response code + human action needed]

Filled instance:

VM: eu-central · 4/16 · rebuilt-from: provision.sh@a1b2c3d
BROWSER: chrome-deb headed:99 · shm=1g · sandbox=off
EGRESS: direct · geo=FR · non-direct-approved-by=n-a
ACCESS: dashboard=127.0.0.1:18789 via ssh-tunnel · public=no
DATA: persists=[cookies,screenshots,logs] · retention=7 days · purge-cron=verified · webhooks=none
CHECKS: display=ok · browser-launch=ok · heartbeat=ok · daemon=ok
BLOCKED: none

Troubleshooting

Scope

This skill ONLY: picks a host for a browser-driving agent; mounts a virtual screen; fixes documented Chromium-on-Linux launch failures; budgets egress by cost tier; keeps the admin shell off the public internet; makes the VM reproducible from a repo and its data purged on a schedule.

This skill NEVER:

• solves, bypasses or routes around CAPTCHAs, bot challenges, MFA, block pages or rate limits — when a defence fires, the run stops and a human takes over;
• changes egress on its own initiative to get past a block — a datacenter-range 403 stops the run; any other tier is a gray-area human decision under the §5 gate, and is not recommended;
• routes around geo-restrictions — a geo-gate is a stated restriction; if the target is geo-blocked, the answer is a lawful local presence or nothing;
• tunes timing or fingerprints to evade detection;
• represents the agent as a human, or hides that an agent is operating. Where the target offers an API, documented automation terms or a declared bot identity, use that rather than driving the UI;
• touches accounts or data you are not authorised to use;
• collects personal data without a named legal basis, minimisation and an enforced retention limit;
• exposes the gateway dashboard publicly.

---

Maintained by Alexandre Bloch (Bloch Agents) · ClawHub @AlexBloch-IA · alex.bloch55@gmail.com