Ubuntu Browser Session

Use the Ubuntu host browser like a long-lived local browser for the agent.

The primary model is site-centric:

• - each important site keeps one default primary identity
• agent tasks reuse that default identity automatically
• non-default identities are allowed only when the user explicitly names a different INLINECODE0
• user help is only for first login, expired sessions, or unrecoverable challenges

When To Use

• - Open, inspect, or interact with a protected site from the Ubuntu Server host
• Reuse an already logged-in site session such as GitHub or Google
• Recover an expired or challenge-blocked session with one bounded round of user help
• Continue browser work on the host without re-authenticating every task

Representative requests:

• - "Use the Ubuntu host browser and open this dashboard."
• "Reuse the existing GitHub login on the server."
• "Continue from the same Google session."
• "Recover this protected page with the least user help."

Do Not Use

• - General web research that only needs HTTP fetch or web search
• Local desktop browsing outside the Ubuntu Server host
• Cases where an API token or non-browser auth flow is enough

Core Rules

• - Default to one primary identity per site
• Do not guess between multiple accounts automatically
• Only use a non-default identity when the user explicitly names a different INLINECODE1
• Prefer local recovery before asking the user to take over
• Treat wrong-page drift as recoverable: first navigate back to the requested site in the same profile, then ask for help only if the target still lands on a login wall or challenge
• Finish the host-browser workflow before switching tools: if open-protected-page.sh returns ready, keep working from this skill's host browser context and do not switch to OpenClaw's generic browser profile or other browser tools unless this workflow is exhausted or the task explicitly requires a different browser stack

Preferred Entry Point

Use the wrapper first:

CODEBLOCK0

The wrapper is responsible for:

• - site-centric profile lookup
• session reuse
• target-page verification
• one automatic recovery attempt when the browser drifted to the wrong page
• bounded escalation to noVNC when user help is actually needed
• keeping work inside the host browser workflow by default instead of mixing in unrelated browser profiles

Site Session Model

Durable default identities are tracked by canonical site, not just exact origin.

Examples:

• - github.com -> default GitHub browser identity
• INLINECODE6 -> default Google browser identity, including INLINECODE7

Persistent state is split across:

• - exact manifests for the live runtime and captured browser state
• a site session registry for default per-site reuse
• compatibility identity aliases for Google-family hosts

Important files:

• - INLINECODE8
• INLINECODE9
• INLINECODE10

Manual Login Recovery

When the wrapper cannot recover locally, it starts the assisted browser overlay and returns:

• - a loopback noVNC URL for SSH tunnel usage
• a LAN noVNC URL when the host IP is known and noVNC is exposed on INLINECODE11

Typical outputs:

CODEBLOCK1

Use the loopback URL if you are forwarding ports over SSH from Windows or another remote machine.

Use the LAN URL only when the host firewall and network allow direct access.

Typical Workflow

1. 1. Try open-protected-page.sh with the requested URL and desired INLINECODE13
2. Let the wrapper resolve the default site identity
3. If the browser is already logged in but sitting on the wrong page, let the wrapper navigate back to the requested site automatically
4. If the target page is ready, continue the task from this host browser workflow first
5. If the target page still shows a login wall or challenge, open the returned noVNC URL
6. After the user finishes the login and leaves the final page loaded, run:

CODEBLOCK2

That finalizes the wrapper-managed session state and updates the site session registry for later reuse.

Do not use assisted-session.sh start as a normal entrypoint. Start with open-protected-page.sh so site-centric profile resolution and wrong-page recovery stay in effect.

Only reach for unrelated browser tooling after this workflow fails to complete the task and you have a concrete reason the host browser workflow is insufficient.

Environment Checks

CODEBLOCK3

Key Files

• - scripts/open-protected-page.sh: main protected-site wrapper
• INLINECODE17: bounded manual takeover and capture
• INLINECODE18: canonical per-site default session registry
• INLINECODE19: site-first profile selection with compatibility fallback
• INLINECODE20: runtime manifest storage and verification support
• INLINECODE21: browser runtime, target selection, and page checks
• INLINECODE22: CDP evaluation, page checks, and navigation
• INLINECODE23: structured page content extraction via CDP

CDP Tools

INLINECODE24 and cdp-snapshot.py stay generic by default.
Forum/search-result helpers are optional enhancements; read references/forum-enhancements.md only when the current page is a forum topic list, category page, or search results page and you need structured topic/result links or text-based clicking.

cdp-eval.py

Evaluate page state or run JavaScript over the Chrome DevTools Protocol.

CODEBLOCK4

Parameters:

• - --port PORT (required): CDP HTTP/WebSocket port
• INLINECODE28: specific target from INLINECODE29
• INLINECODE30: built-in page state checks
• INLINECODE31: arbitrary JavaScript for INLINECODE32
• INLINECODE33: navigate to URL via INLINECODE34
• INLINECODE35: click the first visible matching anchor; when combined with --navigate, pair it with --wait-navigation or --wait-for so the destination DOM is ready before clicking
• INLINECODE39: wait for Page.loadEventFired after INLINECODE41
• INLINECODE42: poll for CSS selector to appear (timeout 10s)

cdp-snapshot.py

Capture structured page content in generic formats by default, plus an optional forum/search-result helper format.

CODEBLOCK5

Output: JSON to stdout INLINECODE43

Parameters:

• - --port PORT (required): CDP HTTP/WebSocket port
• INLINECODE45: specific target from INLINECODE46
• INLINECODE47: output format (default: markdown)
• INLINECODE49: truncate content to N chars (default: 8000, 0=unlimited)

For topic-links, meta is best-effort surrounding text truncated to 400 characters.

See also:

• - INLINECODE52
• INLINECODE53
• INLINECODE54
• INLINECODE55
• INLINECODE56
• INLINECODE57
• INLINECODE58