Clawbridge

ClawBridge

Bridge Open-Source AI Agents to Your Desktop & Browser

ClawBridge is a local-first AI agent platform that unifies multiple automation engines — browser-use, OpenClaw, and Anthropic computer-use — into a single dashboard with task management, live streaming, and safety controls.

Submit a task, pick an engine (or let Auto choose), and watch it run. Everything stays on your machine — or bridge to the cloud.

Version: 0.5.3 | Website | [Changelog](CHANGELOG.md) | Discord

---

Repository

GitHub: NickRomanek/clawbridge

Installation

Windows Installer (Recommended)

Download ClawBridge-Setup.exe and run it. The installer:

1. Installs ClawBridge to C:\Program Files\ClawBridge (or user folder)
2. Bundles Python 3.12, Playwright, and all dependencies
3. Creates Start Menu shortcuts
4. Optionally installs OpenClaw engine (can also install later from dashboard)
5. Creates .env from template on first run
6. Shows a progress bar during post-install setup (Playwright download, engine config)

Optional installer tasks:

• Desktop shortcut: Quick access from your desktop
• Start with Windows: Auto-launch on login
• Install OpenClaw: Adds memory & skills support (recommended for power users)

After installation, launch ClawBridge from the Start Menu and open http://127.0.0.1:8765 in your browser.

macOS Installer (Coming Soon)

macOS support is in development. The platform abstraction layer is complete, but the macOS build is not yet production-ready. Stay tuned for updates.

Quick Start (Single File)

The monolith clawbridge.py is the primary entry point — one file, no package structure needed:

pip install fastapi uvicorn pydantic python-dotenv httpx websockets anthropic pyautogui mss pillow pywinauto pynput
# Copy .env.example to .env and add at least one API key
cp .env.example .env
python clawbridge.py

Opens http://127.0.0.1:8765 — the ClawBridge Dashboard.

Quick Start (Docker)

git clone 
cd clawbridge
cp .env.example .env
# Edit .env -- add at least one API key
docker-compose up

Open http://localhost:8765 in your browser.

Quick Start (Manual Package Install)

Requires: Python 3.11+, Node 22+ (for OpenClaw)

cp .env.example .env
# Edit .env -- add at least one API key
pip install -e .
python -m clawbridge

---

Getting Started

When you first open ClawBridge, you'll see a Getting Started checklist to help you set up:

1. Configure an API Key

ClawBridge requires at least one LLM provider API key. Get yours here:

| Provider | Get Key | Used By | |----------|---------|---------| | Anthropic | console.anthropic.com/settings/keys | browser-use, computer-use | | OpenAI | platform.openai.com/api-keys | browser-use | | OpenRouter | openrouter.ai/keys | All engines (proxy) |

Add your key in the dashboard's Config panel or edit .env directly.

2. Set Your Identity (Optional)

Customize the agent's personality by editing workspace/memory/IDENTITY.md. This gives the AI context about who it's helping.

3. Run Your First Task

Type a task in the chat input and press Enter:

• Web task: "Search Google for ClawBridge AI"
• Desktop task: "Open Notepad and write Hello World"
• Research task: "What are the top 3 news stories today?"

4. Launch Browser Engine

For authenticated web tasks (tasks that need your logins), click Launch Chrome Session in the Config panel. This opens Chrome with a persistent profile where you can sign into your accounts once.

---

Architecture

ClawBridge has two deployment forms that share the same logic:

| Form | File | Use Case | |------|------|----------| | Monolith | clawbridge.py (~12,700 lines) | Primary. Single file, easy to share/deploy | | Package | clawbridge/ directory | Modular. For development, testing, extensibility |

How It Works

User → Dashboard (http://127.0.0.1:8765)
         ↓
    Task Manager (routes, queues, concurrency)
         ↓
    Engine Selection (auto or manual)
         ↓
  ┌──────┼──────────┐
  ↓      ↓          ↓
browser-use  computer-use  OpenClaw
(Playwright)  (pyautogui)   (Node.js CDP)
                 ↑
           Perception Layer
           (screenshot + UIA accessibility)
                 ↑
           Recorder / Replay
           (pynput capture → adaptive replay)
  ↓      ↓          ↓
  └──────┼──────────┘
         ↓
    Live View (WebSocket screenshots)
    Audit Log (SQLite)
    Result Synthesis

---

Engines

| Engine | Technology | Best For | Status | |--------|-----------|----------|--------| | browser-use | Python + Playwright | Web automation, extraction, form filling | Working | | computer-use | Anthropic API + pyautogui + mss + pywinauto | Full desktop control — any app, any window | Working (accessibility-first navigation) | | OpenClaw | Node.js + Chrome DevTools Protocol | AI agent with persistent memory & skills | Requires separate install (npm i -g openclaw) |

Engine Selection (Smart Auto Routing)

ClawBridge uses intelligent engine selection to pick the best engine for each task:

| Task Type | Routes To | Detection | |-----------|-----------|-----------| | Web tasks | browser-use | URLs, "search", "browse", "navigate", web domains | | Desktop tasks | computer-use | App names (notepad, excel, telegram), "click", "open app", "desktop" | | General tasks | openclaw | Fallback for conversational/research tasks |

• Auto mode (default): Smart selection based on URL patterns and keyword detection
• Manual mode: User picks engine explicitly from dropdown
• Economy mode: Toggle Performance/Economy to use cheaper models (gpt-4o-mini for browser-use, Haiku for replay steps)

Computer-Use Engine Details

The computer-use engine controls the full desktop via screenshots + mouse/keyboard. Key features:

• Accessibility-first navigation: Uses Windows UIA (via pywinauto) to enumerate interactive elements. Model clicks by element ID instead of guessing pixel coordinates — far more reliable.
• Dual screenshot strategy: Sends full screen (for coordinates) + zoomed crop of foreground window (for reading text)
• Auto-focus: Detects target app from prompt and brings it to foreground before starting
• DPI-aware: Calls SetProcessDPIAware() so all coordinate systems (pyautogui, mss, GetWindowRect) are consistent
• Forced reasoning: Model must follow [OBSERVE]/[GOAL]/[PLAN]/[ACTION] protocol before every action
• Stale detection: Perceptual hash comparison warns when screenshots don't change after an action
• Hybrid mechanical + AI execution: Deterministic actions (app launch, URL navigation, typing) handled programmatically at zero AI cost. AI only invoked when visual reasoning is needed.
• Mechanical pre-navigation: Extracts URLs from prompts and navigates deterministically via webbrowser.open_new() or Ctrl+L hotkeys before AI engagement — saves an entire round of LLM reasoning.
• Vision fallback: When UIA tree returns = 0.95**: Pure mechanical replay (free, instant)
• 0.7 - 0.95: Mechanical + visual verification (window title, perceptual hash, LLM check)
• **, /do , /browser, /computer, /chat`
• Stop button: Send button swaps to red Stop while a task is running — always visible, one-click cancel
• Workflow recording from chat: Click Record, perform actions, click Stop — save card appears with pre-filled name
• Live View: Real-time screenshot stream from browser or desktop
• Engine status: See which engines are available/running/errored
• Config panel: API key management, browser session controls, machine ID
• Activity feed: Audit trail of every action taken
• Workflows tab: Record, save, and replay desktop workflows
• Soul/Memory tabs: Edit agent personality and view memory logs

Configuration

All configuration lives in .env. See .env.example for the full list.

API Keys (BYOK)

You need at least one:

| Key | Provider | Used By | |-----|----------|---------| | ANTHROPIC_API_KEY | Anthropic (direct) | browser-use, computer-use | | OPENAI_API_KEY | OpenAI | browser-use | | OPENROUTER_API_KEY | OpenRouter (proxy) | computer-use, browser-use |

Key Settings

# Server
CLAWBRIDGE_HOST=127.0.0.1
CLAWBRIDGE_PORT=8765

# Engines
ENABLED_ENGINES=browser_use,computer_use    # comma-separated
DEFAULT_MODEL=openai/gpt-4o                 # for browser-use

# Computer-Use
COMPUTER_USE_MODEL=anthropic/claude-sonnet-4.5   # primary model
COMPUTER_USE_MODEL_FAST=anthropic/claude-haiku-4-5  # cheap model for routine replay
COMPUTER_USE_API=auto                            # auto | direct | openrouter
COMPUTER_USE_MAX_SCREEN_WIDTH=1920
COMPUTER_USE_MAX_SCREEN_HEIGHT=1080
COMPUTER_USE_ACTION_DELAY_MS=500

# Economy Mode
ECONOMY_MODEL=                                   # optional: google/gemini-flash-2.0

# Recording
RECORDING_SCREENSHOTS=true
RECORDING_INTENT_EXTRACTION=true
SCREENPIPE_INTEGRATION=true

# Browser
BROWSER_HEADLESS=true
BROWSER_MODE=default                        # default | cdp | user_data_dir
BROWSER_CDP_URL=http://localhost:9222
BROWSER_USER_DATA_DIR=

# Policy
POLICY_MODE=guarded                         # guarded | permissive | strict
MAX_CONCURRENT_TASKS=3
MAX_ACTIONS_PER_TASK=50

# Remote Bridge (beta)
REMOTE_BRIDGE_URL=
REMOTE_AUTH_TOKEN=

Automation Modes

ClawBridge supports two automation modes to balance speed vs. safety:

| Mode | Behavior | Best For | |------|----------|----------| | Supervised (default) | Pauses for approval before high-risk actions | Financial tasks, unfamiliar workflows, production systems | | Autonomous | Runs without interruption | Trusted tasks, development, demos |

Supervised Mode Features

When running in Supervised mode, ClawBridge automatically detects and pauses for:

Sensitive Domains (banking, shopping, cloud admin):

• Banking: chase.com, bankofamerica.com, wellsfargo.com, paypal.com, etc.
• Shopping: amazon.com, ebay.com, walmart.com checkout pages
• Cloud: console.aws.amazon.com, portal.azure.com, console.cloud.google.com
• Email: gmail.com, outlook.com (compose/send actions)

High-Risk Actions:

• Purchases and payments (buy, purchase, checkout, pay)
• Form submissions (submit, confirm, send)
• Deletions (delete, remove, clear)
• Account changes (password, settings, account)

When a high-risk action is detected:

1. Task pauses and shows an approval modal in the dashboard
2. You see exactly what action the AI wants to take
3. Click Approve to proceed or Deny to block
4. 2-minute timeout auto-denies if no response

Changing Modes

From Dashboard: Use the Automation Mode toggle in the Config panel

From .env:

AUTOMATION_MODE=supervised   # or: autonomous

Tip: Start with Supervised mode until you're comfortable with the AI's behavior, then switch to Autonomous for trusted workflows.

---

Security

• All data stays on your machine in local mode. No cloud egress.
• API keys are never logged or transmitted.
• Dashboard authentication: Token-based auth with HttpOnly cookie, CSRF token protection on all state-changing endpoints.
• WebSocket authentication: Token verified before connection is accepted.
• Actions classified as safe/sensitive/high-risk with configurable policy.
• Sensitive domain detection (banking, cloud consoles) auto-elevates risk level.
• Credential and PII detection with automatic redaction before memory storage.
• Prompt injection pattern detection and filtering in stored memory.
• Path traversal protection on personality file endpoints.
• Remote bridge requires HTTPS for non-localhost URLs.
• XSS protection via DOMPurify with safe fallback.
• Full audit trail in SQLite database.

API Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | / | Dashboard UI | | GET | /health | Health check | | POST | /api/tasks | Create task | | GET | /api/tasks | List all tasks | | GET | /api/tasks/{id} | Get single task | | PATCH | /api/tasks/{id} | Pause/resume/cancel | | DELETE | /api/tasks/{id} | Remove task | | DELETE | /api/tasks | Clear all tasks | | GET | /api/tasks/{id}/steps | Get step-by-step replay | | GET | /api/engines | List engines + status | | POST | /api/engines/openclaw/install | Install OpenClaw engine | | GET | /api/config | Get config (keys redacted, includes version) | | POST | /api/config/keys | Save API keys to .env | | POST | /api/config/automation | Set automation mode (supervised/autonomous) | | POST | /api/browser/launch | Launch Chrome with CDP | | GET | /api/browser/status | Check Chrome connection | | GET | /api/schedules | List task schedules | | POST | /api/schedules | Create recurring schedule | | DELETE | /api/schedules/{id} | Delete schedule | | GET | /api/templates | List task templates | | POST | /api/templates | Create task template | | GET | /api/workflows | List saved workflows | | GET | /api/workflows/{id} | Get workflow details | | POST | /api/workflows | Create workflow from recorded actions | | DELETE | /api/workflows/{id} | Delete workflow | | POST | /api/workflows/{id}/replay | Trigger workflow replay | | POST | /api/workflows/{id}/replay-parameterized | Replay with parameter substitution | | POST | /api/workflows/{id}/save-params | Save parameter defaults | | POST | /api/workflows/{id}/extract-intent | Trigger intent extraction | | POST | /api/config/model-tier | Switch Performance/Economy mode | | POST | /api/config/computer-use-api | Switch API path (Auto/Direct/OpenRouter) | | POST | /api/recording/start | Start desktop recording | | POST | /api/recording/stop | Stop recording, return actions | | POST | /api/auth/login | Authenticate and set HttpOnly session cookie | | WS | /ws | WebSocket (tasks, frames, audit, approvals, workflows) |

WebSocket Events

| Event Type | Direction | Description | |------------|-----------|-------------| | task_update | Server → Client | Task status change | | browser_frame | Server → Client | Screenshot stream (base64) | | audit_event | Server → Client | Audit log entry | | approval_request | Server → Client | High-risk action needs approval | | approval_response | Client → Server | User approves/denies action | | approval_ack | Server → Client | Confirmation of approval processing | | recording_status | Server → Client | Recording started/stopped status | | recording_result | Server → Client | Recorded actions after stop | | workflow_update | Server → Client | Workflow list changed | | workflow_saved | Server → Client | Workflow saved confirmation | | replay_started | Server → Client | Workflow replay task created | | recording_event | Server → Client | Live action during recording | | engine_status | Server → Client | Engine status/model info changed | | config_update | Server → Client | Configuration setting changed | | safety_warning | Server → Client | Safety scan flag detected |

Remote Bridge (Beta)

ClawBridge can connect to a remote orchestration service:

• Set REMOTE_BRIDGE_URL and REMOTE_AUTH_TOKEN in .env
• Local instance polls remote for tasks every 10 seconds
• Each machine identified by persistent clawbridge.id (UUID)
• Remote tasks execute locally, results flow back
• Dashboard shows "Bridge Online/Offline" status

This enables the bridge architecture: local machines provide the "hands" (desktop/browser access), remote service provides the "brain" (task o

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NickRomanek
• Source: NickRomanek/clawbridge
• License: Apache-2.0
• Homepage: https://clawbridge.ai

Install and usage instructions live in the source repository linked above.