Dokobot Remote Browser Skill

A clean Agent skill for using a remote real browser through Dokobot CLI over SSH.

The controller does not scrape from its own IP and does not run a second browser stack. It asks an SSH-reachable browser host to run dokobot read --local, then receives rendered Markdown back over stdout.

Agent / controller
  └─ SSH / Tailscale SSH
      └─ Browser host
          ├─ Dokobot CLI
          ├─ Dokobot native bridge
          └─ Chrome / Edge / Brave / Arc + browser session

What this is for

Use this pattern when an Agent needs to:

• search from a stable, trusted browser environment;
• read JavaScript-rendered pages as Markdown;
• reuse existing browser cookies/login state without sharing site passwords with the Agent;
• avoid poor VPS search quality, bot-detection, geolocation, or IP reputation issues;
• keep browser execution on a long-lived desktop while the Agent runs elsewhere.

The job is not remote desktop and not crawler infrastructure. The job is:

command in, rendered Markdown out.

Current best practice

Do not duplicate Dokobot or build another browser wrapper unless there is a concrete gap.

Preferred flow:

1. SSH to the browser host.

2. Run:

   dokobot --version && dokobot doko list

3. If doko list shows multiple local bridges, pick one device id for the run.

4. Search by reading a rendered search URL:

   dokobot read --local --device "DEVICE_ID" "https://www.google.com/search?q=RAG+pipeline+best+practices&num=10&hl=en&gl=us"

5. Deep-read selected results:

   dokobot read --local --device "DEVICE_ID" "https://example.com/article"

6. Fall back to another search tool only if SSH, Dokobot, the bridge, or the browser host is down.

If exactly one local bridge exists, --device can be omitted. In automated Agent workflows, detecting and passing the device explicitly is more robust.

Boundary conditions

Controller side

• Can reach the browser host over SSH, VPN, private network, or Tailscale.
• Has an SSH client or library, for example ssh, ssh2, Paramiko, Fabric, etc.
• Stores credentials outside prompts and repositories.

Browser host side

• Has an SSH server / remote command entrypoint.

  • Windows: OpenSSH Server or Tailscale SSH.
  • macOS/Linux: sshd or equivalent.

• Has Node.js/npm and @dokobot/cli installed.

• dokobot is available in the non-interactive SSH shell PATH.

• Has Chrome, Edge, Brave, or Arc installed.

• Has the Dokobot browser extension installed.

• Has the Dokobot native bridge installed and connected:

  dokobot install-bridge

• The target browser session is alive enough for the bridge to respond.

• The user profile/cookies needed for logged-in pages exist on that browser host.

Network / security

• Do not expose Chrome DevTools ports publicly.
• Prefer private networking: Tailscale, WireGuard, private LAN, or a locked-down SSH bastion.
• Treat the browser host as privileged: the Agent can read whatever that browser session can read.
• Keep credentials in env vars, secret files, or vaults. Never commit them.

Non-goals

This skill is not for:

• clicking through complex multi-step workflows;
• CAPTCHA solving;
• bypassing per-site authorization or anti-abuse rules;
• high-concurrency crawling;
• replacing Playwright/CDP when DOM-level interaction is required.

Optional helper script

This repository includes scripts/dokobot-ssh-read.js as a small convenience helper for SSH credentials and shell quoting.

It is optional. The skill itself intentionally stays centered on the official Dokobot CLI.

Install dependencies:

npm install

Configure credentials via environment variables:

export DOKOBOT_SSH_HOST="browser-host-or-private-ip"
export DOKOBOT_SSH_USER="agent"
export DOKOBOT_SSH_PASSWORD="***"        # or use DOKOBOT_SSH_KEY
export DOKOBOT_REMOTE_SHELL="powershell" # posix | powershell | cmd
export DOKOBOT_DEVICE="..."              # optional; useful when multiple bridges exist

Health check:

node scripts/dokobot-ssh-read.js --health

Read a URL:

node scripts/dokobot-ssh-read.js --url "https://example.com"

Search Google through the remote browser:

node scripts/dokobot-ssh-read.js --query "RAG pipeline best practices" --gl us --hl en

See examples/env.example for all variables.

Failure modes

Symptom	Likely cause	Fix
SSH timeout	Host offline, VPN down, firewall closed	Verify SSH reachability first
dokobot: command not found	CLI not installed or not in non-interactive shell PATH	Install @dokobot/cli; fix PATH for SSH shell
No local device in doko list	Bridge/browser not connected	Restart browser, reload extension, rerun dokobot install-bridge
Multiple bridges found	More than one local browser bridge is connected	Pass --device <id> or set DOKOBOT_DEVICE from dokobot doko list
dokobot search is unavailable or needs API config	Local browser mode is handled by read --local	Build a search URL and use dokobot read --local <search-url>
Empty or partial page	Page blocks automation, requires interaction, or needs more wait/scroll	Tune Dokobot read options or use manual/browser automation
Logged-in content missing	Browser host is not logged in under the active profile	Log in on the browser host
Social detail page blocked while list works	Site uses token/referer validation	Use search/list pages as boundary data; do not assume details are readable

Validation snapshot

A practical regression pass should include:

• health/version/device list;
• Google English search;
• Google Chinese search;
• Google News tab;
• a static deep-read page;
• a JavaScript-heavy page;
• one social/community page if relevant;
• a small 2-3 concurrency burst.

Reference Hermes run on 2026-04-28 after explicit device handling:

• 20/20 cases OK;
• average ~9s;
• p90 ~13s;
• max ~16s;
• tested Google English/Chinese/News, Reddit, YouTube, Wikipedia, GitHub, and a social search-list boundary case.

Minimal mental model

The remote machine is not a proxy.

The remote machine is the browser.

The Agent only sends Dokobot commands and reads Markdown.