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

> Learn to integrate browser skills into WeKnora with our setup and usage guide. Execute native browser actions via WebSocket CDP commands without local sandboxing. Explore Tencent/BrowserSkill today.

- Repository: [Tencent/WeKnora](https://github.com/tencent/WeKnora)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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:

```dotenv

# .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:

```bash
./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`](https://github.com/Tencent/WeKnora/blob/main/client/skill.go):

```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:

```json
{
  "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:

```json
{
  "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:

```javascript
// 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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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.