| name | web-access |
| description | Use this skill for web browsing, logged-in websites, social platforms, dynamic pages, screenshots, downloads, and any task that needs a real browser session. |
| allowed-tools | Bash |
web-access
Use this skill as the single external entry point whenever a task needs web access. Do not present WebSearch, WebFetch, curl, Jina, raw CDP, host IPC, or Docker sidecar as choices for the agent to pick manually.
Routing Model
Use staged routing:
S1: static public access through WebSearch, WebFetch, or curlS2: Jina readerS3: real browser automation through this project's browser bridge
Move from a lower stage to a higher stage only after a current-round failure is confirmed. Current-round failures include fetch errors, empty or irrelevant results, login walls, anti-bot blocking, missing dynamic content, incomplete screenshots, or content that requires cookies.
Historical route cache may influence the starting stage. It must not override current evidence. If the chosen stage fails in this round, upgrade.
Browser Architecture
Primary path for Docker and Linux:
agent / skill
-> requestHostBrowser()
-> WEB_ACCESS_BROWSER_PROVIDER=direct_cdp
-> LocalCdpBrowser
-> http://172.31.250.10:9223
-> Docker Chrome sidecar
Legacy fallback for Windows host development only:
agent / skill
-> requestHostBrowser()
-> .data/browser-ipc
-> host-browser-bridge-daemon.mjs
-> Windows Chrome CDP
The function name requestHostBrowser() is legacy. In Docker sidecar mode it does not mean "use Windows host IPC"; it dispatches directly to the sidecar CDP backend before IPC is attempted.
Startup
Always start with:
node /app/runtime/skills-user/web-access/scripts/check-deps.mjs
If you are debugging from the Windows project directory instead of the /app container, use:
node runtime/skills-user/web-access/scripts/check-deps.mjs
Expected healthy output in Docker sidecar mode:
host-browser: ok (http://172.31.250.10:9223)
proxy: ready (127.0.0.1:3456)
The host-browser label is kept for compatibility with older scripts. In sidecar mode it means "browser backend is reachable", not "Windows host IPC is active".
Use these project-level sidecar commands from the repository root:
npm run docker:chrome:check
npm run docker:chrome:status
npm run docker:chrome:open
npm run docker:chrome:restart
Use docker:chrome:restart only when Chrome itself needs a kick. It keeps the persistent profile but clears stale Chrome locks and crash-restore prompt state.
Legacy Host IPC Fallback
Only use the Windows host IPC bridge when sidecar mode is not configured or when explicitly debugging the legacy Windows path.
The legacy launcher is:
powershell -ExecutionPolicy Bypass -File .\scripts\start-web-access-browser.ps1
Do not tell a Docker sidecar user to start this launcher just because Chrome is unavailable. If WEB_ACCESS_BROWSER_PROVIDER=direct_cdp is set, first check the sidecar services and CDP endpoint.
Sidecar Login And Profile
Sidecar facts:
- GUI login entrypoint:
https://127.0.0.1:3901/
- CDP endpoint inside compose:
http://172.31.250.10:9223
- Persistent profile on the host:
.data/chrome-sidecar
- Chrome profile inside the sidecar container:
${WEB_ACCESS_BROWSER_PROFILE_DIR:-/config/chrome-profile-sidecar}
- Browser-reachable app base URL:
WEB_ACCESS_BROWSER_PUBLIC_BASE_URL=http://ugk-pi:3000
Manual login and automation must use the same profile path. Do not split manual login and auto-start across different profile directories.
Chrome must stay on DISPLAY=:0 with --ozone-platform=x11. Do not switch it back to Wayland unless Chrome top-layer UI clicks are revalidated.
Local Artifact URLs
Container workspace paths such as /app/runtime/..., /app/public/..., and file:///app/... are valid internal artifact inputs for this skill.
The browser bridge resolves supported local artifacts to an HTTP URL before Chrome opens them:
/app/runtime/report.html
-> http://ugk-pi:3000/v1/local-file?path=%2Fapp%2Fruntime%2Freport.html
Keep these two URL bases separate:
PUBLIC_BASE_URL: user-visible links, such as http://127.0.0.1:3000 locally or a public domain in productionWEB_ACCESS_BROWSER_PUBLIC_BASE_URL: browser-automation links inside the compose network, normally http://ugk-pi:3000
Do not make sidecar Chrome open http://127.0.0.1:3000/.... Inside the browser container that points at the browser container itself, not the ugk-pi app.
Do not make sidecar Chrome open file:///app/.... The sidecar is a different container and does not own the app container's filesystem view.
Only in the final user-facing answer should you avoid raw container paths. For user delivery, return the PUBLIC_BASE_URL-reachable link or use send_file.
Local Proxy API
When check-deps.mjs passes, a compatibility proxy is available at http://127.0.0.1:3456 inside the app container.
Common endpoints:
curl -s http://127.0.0.1:3456/health
curl -s http://127.0.0.1:3456/targets
curl -s "http://127.0.0.1:3456/new?url=https%3A%2F%2Fexample.com"
curl -s "http://127.0.0.1:3456/session/target?metaAgentScope=${AGENT_SCOPE}"
curl -s -X POST "http://127.0.0.1:3456/session/target?target=ID&metaAgentScope=${AGENT_SCOPE}"
curl -s -X DELETE "http://127.0.0.1:3456/session/target?metaAgentScope=${AGENT_SCOPE}"
curl -s -X POST "http://127.0.0.1:3456/session/close-all?metaAgentScope=${AGENT_SCOPE}"
curl -s "http://127.0.0.1:3456/info?target=ID"
curl -s -X POST "http://127.0.0.1:3456/eval?target=ID" -d 'document.title'
curl -s "http://127.0.0.1:3456/navigate?target=ID&url=https%3A%2F%2Fexample.com"
curl -s -X POST "http://127.0.0.1:3456/click?target=ID" -d 'button.submit'
curl -s "http://127.0.0.1:3456/scroll?target=ID&direction=bottom"
curl -s "http://127.0.0.1:3456/screenshot?target=ID&file=/tmp/page.png"
curl -s "http://127.0.0.1:3456/close?target=ID"
When passing a nested URL into /new or /navigate, URL-encode it first. Otherwise query params inside the target URL can be mistaken for proxy params.
Working Style
Define the current agent scope once when browser work may span multiple commands:
AGENT_SCOPE="${CLAUDE_AGENT_ID:-${CLAUDE_HOOK_AGENT_ID:-${agent_id:-}}}"
Use that scope on proxy requests with metaAgentScope=${AGENT_SCOPE} so the proxy can reuse the current agent-owned target instead of competing for a shared page.
For a concrete URL, prefer the automatic runner:
node /app/runtime/skills-user/web-access/scripts/staged-route-cli.mjs run-url --url "https://example.com" --task-kind "open_page"
Only use recommend or report for manual route debugging.
Prefer eval for extraction. Open your own target with /new. Close targets you created unless you intentionally keep an agent-owned page alive for follow-up work.
