How to Integrate Browser Skills into WeKnora: Complete Setup and Usage Guide

WeKnora integrates browser skills by deploying the Tencent/BrowserSkill daemon alongside a Chrome extension, enabling LLM agents to execute native browser actions through WebSocket CDP commands without requiring local sandboxed execution.

WeKnora is an open-source LLM orchestration platform developed by Tencent that supports native browser automation through integration with Tencent/BrowserSkill. This capability allows agents to navigate websites, capture screenshots, and interact with DOM elements directly through a paired Chrome instance rather than restricted sandboxed environments.

Architecture of Browser Skill Integration

The integration relies on three coordinated layers that bridge the WeKnora backend with a user-controlled Chrome browser.

Server-Side Daemon Layer

At the core, internal/browserskill/authorization.go implements a Go service that manages the BrowserSkill lifecycle. The daemon launches the bsk binary and exposes a WebSocket endpoint at /api/v1/local-browser/extension to handle persistent connections from Chrome extensions. It maintains device authentication state in two PostgreSQL tables defined in migrations/versioned/000093_browser_authorization.up.sql: browser_devices for permanent identifiers and browser_pairings for short-lived authorization tokens with indexed expiry (browser_pairings_expiry).

Chrome Extension Component

The extension, packaged as browser-skill-weknora-0.2.1.zip and built via scripts/build_browserskill.sh, connects to the daemon through the WebSocket URL. It receives Remote Procedure Call (RPC) commands, translates them into Chrome DevTools Protocol (CDP) instructions using the patched implementation in patches/browserskill/remote-extension-connection.patch, and streams back screenshots, DOM snapshots, and execution reports. The extension respects configured timeouts of 3 seconds for screenshots and 10 seconds for DOM reads.

Frontend Coordination Interface

The Vue.js settings page at frontend/src/views/settings/BrowserConnectionSettings.vue provides the pairing workflow. Users download the extension archive, install it manually in Chrome, and input a one-time pairing link generated by the daemon. The UI also renders low-resolution JPEG previews (≤640 px) of active browser tasks and exposes controls to pause, resume, or terminate specific task sessions without affecting the entire browser.

Deploying the BrowserSkill Infrastructure

Docker Environment Configuration

Deploy WeKnora with the BrowserSkill daemon embedded by configuring these environment variables in your container orchestration:

# .env or docker-compose environment

BROWSERSKILL_BINARY=/opt/weknora/browserskill/bsk
BROWSERSKILL_EXTENSION_PATH=/opt/weknora/browserskill/browser-skill-weknora-0.2.1.zip

# Optional: override public WebSocket URL for reverse proxy setups

# BROWSERSKILL_PUBLIC_URL=wss://weknora.example.com/api/v1/local-browser/extension

The docker/Dockerfile.app image bundles the bsk binary and extension archive, exposing these paths to the Go runtime.

Building the Extension from Source

For native deployments or custom patches, compile the artifact using the provided build script:

./scripts/build_browserskill.sh ./artifacts/browserskill linux/amd64

This script clones the BrowserSkill source, applies patches/browserskill/remote-extension-connection.patch, and produces the distributable ZIP at artifacts/browserskill/browser-skill-weknora-0.2.1.zip.

Device Pairing and Authentication Workflow

Integrating a browser instance requires cryptographic pairing between the extension and the WeKnora daemon:

1. Initiate Pairing: In Settings → 浏览器连接, the user clicks 下载配套扩展 to download the ZIP, then loads it via Chrome's Extensions page in developer mode.
2. Generate Token: The UI creates a one-time pairing URL at /api/v1/local-browser/extension/authorize?... containing a short-lived token.
3. Extension Registration: The user pastes the URL into the extension's “远程连接” field, triggering the daemon to persist a device record in browser_devices and a temporary entry in browser_pairings.
4. Persistent Access: Once paired, the extension maintains a WebSocket connection, allowing multiple conversations to share the same Chrome instance while isolating each task's permissions.

Executing Browser Actions via LLM Agents

To trigger browser automation from an agent, set LocalBrowserEnabled: true in the skill request struct defined in client/skill.go:

req := &skill.Request{
    Model: "gpt-4o-mini",
    Prompt: "Navigate to the WeKnora documentation and capture the architecture diagram.",
    LocalBrowserEnabled: true,  // Activates BrowserSkill RPC translation
}
resp, err := client.CallSkill(ctx, req)

The SDK automatically encodes the request into a BrowserSkill RPC payload:

{
  "method": "navigate",
  "url": "https://weknora.com/docs"
}

To keep a page open after task completion—preserving state for user review—include the keep_open flag:

{
  "method": "navigate",
  "url": "https://example.com/dashboard",
  "keep_open": true
}

Task Isolation and Safety Mechanisms

WeKnora implements strict isolation boundaries to prevent LLM agents from accessing arbitrary user tabs or hanging indefinitely.

CDP Session Management

Every browser call initializes a distinct task with its own CDP session. The extension tags new tabs opened during task execution and adds them to a task-specific tab group. Upon task completion or manual termination, the daemon closes the CDP connection and recycles associated tabs, ensuring the agent cannot hijack unrelated browsing sessions.

Timeout Configuration and UI Controls

Commands exceeding their allotted timeouts (3 seconds for visual capture, 10 seconds for DOM traversal) are automatically aborted, with execution logs retained for debugging. Users can manually control active tasks through the frontend:

// Pause a running browser task
await fetch('/api/v1/local-browser/task/pause', {
  method: 'POST',
  body: JSON.stringify({task_id: "task_abc123"})
});

// Resume execution
await fetch('/api/v1/local-browser/task/resume', {
  method: 'POST',
  body: JSON.stringify({task_id: "task_abc123"})
});

The daemon caches screenshots for approximately one second, and the frontend only requests new frames when the preview pane is visible, minimizing bandwidth consumption.

Summary

• WeKnora browser skill integration relies on a Go daemon (internal/browserskill/authorization.go), a Chrome extension, and a WebSocket transport layer to execute CDP commands.
• Deployment requires setting BROWSERSKILL_BINARY and BROWSERSKILL_EXTENSION_PATH environment variables, typically handled automatically in the official Docker image.
• Authentication uses device-pairing tables (browser_devices and browser_pairings) to establish persistent, secure connections between the extension and server.
• Agent activation occurs by setting LocalBrowserEnabled: true in client/skill.go skill requests, which translates natural language prompts into structured browser RPCs.
• Safety features include per-command timeouts, task-scoped CDP sessions, and frontend controls to pause or terminate specific browser tasks without affecting the global Chrome instance.

Frequently Asked Questions

What is the BrowserSkill daemon in WeKnora?

The BrowserSkill daemon is a Go service located in internal/browserskill/authorization.go that manages the lifecycle of native browser automation. It launches the bsk binary, handles WebSocket connections from Chrome extensions at /api/v1/local-browser/extension, and maintains device pairing state in PostgreSQL tables to authenticate browser instances before allowing CDP command execution.

How does device pairing work between WeKnora and Chrome?

Device pairing uses a temporary token system. The frontend generates a one-time URL via /api/v1/local-browser/extension/authorize containing a pairing token stored in browser_pairings. When the user pastes this URL into the Chrome extension's remote connection field, the daemon verifies the token, creates a permanent entry in browser_devices, and establishes a persistent WebSocket tunnel for subsequent RPC commands.

What timeout limits exist for browser commands in WeKnora?

BrowserSkill enforces strict timeouts to prevent hanging operations: 3 seconds for screenshot capture and 10 seconds for DOM reading operations. Commands exceeding these limits are automatically aborted, and the extension logs any command taking longer than 2 seconds for debugging purposes. These thresholds are hardcoded in the extension's CDP wrapper logic within the patched BrowserSkill source.

Can multiple LLM tasks share the same paired Chrome instance?

Yes. Once a Chrome extension is paired, the daemon stores the device association in browser_devices, allowing multiple conversations to reuse the connection. However, task isolation ensures each browser call creates a dedicated CDP session with uniquely tagged tabs; when a specific task ends, only its associated tabs close, leaving other tasks and the main browser window unaffected.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}