Agent Skills › rcarmo/piclaw › cdp-browser-vnc-setup

cdp-browser-vnc-setup

GitHub

用于检查和配置 CDP 浏览器 VNC 环境，提供 Linux 自动安装、macOS/Windows 手动配置指南及故障排查。

runtime/skills/integrations/cdp-browser-vnc-setup/SKILL.md rcarmo/piclaw

触发场景

CDP browser VNC 依赖缺失准备浏览器查看环境 VNC 连接或显示异常

安装

npx skills add rcarmo/piclaw --skill cdp-browser-vnc-setup -g -y

更多选项

非标准路径

npx skills add https://github.com/rcarmo/piclaw/tree/main/runtime/skills/integrations/cdp-browser-vnc-setup -g -y

不安装直接使用

npx skills use rcarmo/piclaw@cdp-browser-vnc-setup

指定 Agent (Claude Code)

npx skills add rcarmo/piclaw --skill cdp-browser-vnc-setup -a claude-code -g -y

安装 repo 全部 skill

npx skills add rcarmo/piclaw --all -g -y

预览 repo 内 skill

npx skills add rcarmo/piclaw --list

SKILL.md

Frontmatter

{
    "name": "cdp-browser-vnc-setup",
    "description": "Check and set up the optional managed Linux desktop used by piclaw:\/\/vnc\/cdp-browser, or explain bring-your-own CDP\/VNC setup on macOS and Windows.",
    "distribution": "public"
}

CDP browser VNC setup

Use this skill when piclaw://vnc/cdp-browser reports missing dependencies or when an operator wants to prepare browser viewing before opening the pane.

Check first

Run the packaged check script from the installed Piclaw package or repository root:

bun runtime/skills/integrations/cdp-browser-vnc-setup/check.ts

The check is read-only. It reports:

platform support;
Xvfb, x11vnc, and xauth availability;
the Chromium-family browser command Piclaw can launch;
whether the stable pane path can use the managed Linux service.

Linux managed setup

Piclaw starts the managed desktop only after an authenticated request opens piclaw://vnc/cdp-browser. It does not start Chromium, Xvfb, or VNC during Piclaw boot.

On Debian or Ubuntu, install the missing packages explicitly:

sudo apt update
sudo apt install xvfb x11vnc xauth chromium

Distribution package names vary. Chrome or Edge can replace Chromium when their executable is in PATH.

After installation:

run the check script again;

optionally run the isolated lifecycle smoke with a disposable workspace:

bun runtime/scripts/managed-cdp-browser-vnc-smoke.ts /tmp/piclaw-cdp-vnc-smoke

open piclaw://vnc/cdp-browser in a Piclaw pane;
use cdp_browser normally—the tool prefers the same managed browser while it is active.

The managed service:

binds CDP and VNC to 127.0.0.1;
disables X11 TCP listening;
uses a private Xauthority cookie;
runs x11vnc with -shared -forever so multiple Piclaw viewers can attach;
stores the Chromium profile under /workspace/.piclaw/browser/profile by default;
stops only processes it launched when Piclaw shuts down.

macOS and Windows

The managed desktop is Linux-only. Bring your own browser and VNC service:

launch Chrome, Edge, or Chromium with a loopback CDP port in the 9224–9233 range;
expose the same visible desktop through a VNC server bound to loopback or an allowlisted private address;
add that VNC endpoint to Piclaw’s configured VNC targets or enable direct targets deliberately;
use the ordinary piclaw://vnc/<target> pane path.

Do not expose unauthenticated CDP or VNC ports to public interfaces.

Troubleshooting

Missing dependencies: install only the packages listed by the pane/check script.
No free display or port: stop stale Xvfb/x11vnc/Chromium processes or inspect ports 5901–5910 and 9224–9233.
Browser starts but CDP does not respond: verify the browser accepts --remote-debugging-address=127.0.0.1 and the selected port.
VNC connects but shows no browser: check the browser process has the same DISPLAY and XAUTHORITY as Xvfb/x11vnc.
Container sandbox: Piclaw uses Chromium’s normal sandbox on native Linux. In recognised Docker, Podman, Kubernetes, or LXC runtimes, it logs a warning and adds --no-sandbox because nested user/network namespaces may be unavailable. Treat the container boundary as the browser isolation boundary, or configure a bring-your-own browser/VNC target if that is unsuitable.