Documentation

Claw Relay — open source trust layer for AI browser agents

Quick Start
Configuration
WebSocket Protocol
Scopes & Permissions
Dashboard
Remote Access
Troubleshooting

Quick Start

Prerequisites

curl -fsSL https://bun.sh/install | bash   # Bun runtime
npm install -g agent-browser               # browser engine
brew install cloudflared                   # remote access (optional)

Install & Run (Bun)

git clone https://github.com/AndreaGriffiths11/claw-relay.git
cd claw-relay/relay-server
bun install
cp config.example.yaml config.yaml        # edit with your agents
bun src/index.ts config.yaml

Install & Run (Rust)

cd claw-relay/relay-core
cargo build --release
./target/release/claw-relay-core ../relay-server/config.yaml

Launch Chrome with Debugging

# macOS — quit Chrome completely first (Cmd+Q)
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug

# Then connect agent-browser
agent-browser connect http://localhost:9222

Or use ./start.sh which handles Chrome, the relay, and tunneling in one command.

Configuration

server:
  port: 9333
  host: "0.0.0.0"

agents:
  my-agent:
    token: "pick-a-strong-secret"
    scopes: ["read", "interact"]
    allowlist: ["github.com", "*.example.com"]
    rateLimit: 30

blocklist:
  - "*.bank.com"
  - "mail.google.com"

audit:
  logFile: "./audit.jsonl"
  logToStdout: true

dashboard:
  port: 9334
  adminToken: "your-admin-token"

⚠️ Each YAML key can only appear once per block. Replace lines — don't add duplicates.

WebSocket Protocol

1. Connect

Connect to ws://localhost:9333 (or your tunnel URL via wss://).

2. Authenticate

{"type": "auth", "token": "your-token", "agent_id": "my-agent"}

3. Send Actions

Action	Scope	Example
`snapshot`	read	`{"type": "snapshot"}`
`screenshot`	read	`{"type": "screenshot"}`
`click`	interact	`{"type": "click", "ref": "e5"}`
`type`	interact	`{"type": "type", "ref": "e3", "text": "hello"}`
`fill`	interact	`{"type": "fill", "ref": "e3", "text": "hello"}`
`press`	interact	`{"type": "press", "key": "Enter"}`
`hover`	interact	`{"type": "hover", "ref": "e2"}`
`select`	interact	`{"type": "select", "ref": "e7", "values": ["opt1"]}`
`navigate`	navigate	`{"type": "navigate", "url": "https://..."}`
`close`	navigate	`{"type": "close"}`
`evaluate`	execute	`{"type": "evaluate", "js": "document.title"}`

4. Responses

// Success
{"type": "result", "action": "snapshot", "ok": true, "data": "..."}

// Error
{"type": "error", "code": "permission_denied", "message": "Agent lacks 'interact' scope"}
{"type": "error", "code": "site_blocked", "message": "mail.google.com is blocked"}

Scopes & Permissions

read — Snapshots and screenshots. Passive observation only.
navigate — Open URLs, close tabs. Subject to allowlist/blocklist.
interact — Click, type, fill forms, hover, select. Active browser control.
execute — Run JavaScript on the page. Full access — use with extreme caution.

Start with read only. Add more when you trust the setup.

Allowlist & Blocklist

Each agent can have an allowlist (only these sites) and a global blocklist (never these sites). Supports glob patterns: *.github.com, docs.example.com. Blocklist is fully customizable.

Dashboard

The built-in dashboard runs on port 9334. Manage agents, view live connections, browse the audit log — all from the browser.

Overview — Connected agents, total actions, uptime
Agents — Add, edit, delete agents with scope pills and status indicators
Audit Log — Filterable, paginated, color-coded. Download or clear
Settings — View current config, version info

Authenticate with your adminToken from config.yaml, or pass it as ?token= in the URL.

Remote Access

Cloudflare Quick Tunnel (easiest)

cloudflared tunnel --url http://localhost:9333

You'll get a URL like https://random-words.trycloudflare.com. Connect via wss://. No account needed.

Quick tunnels are temporary — the URL changes on restart. For persistent URLs, set up a named Cloudflare tunnel.

Tailscale

If both machines are on the same tailnet: ws://<tailscale-ip>:9333

ngrok

ngrok http 9333

The tunnel only provides transport. Every connection still requires a valid agent token. Scopes, allowlists, blocklists, and rate limits all apply regardless of how the agent connects.

Troubleshooting

Problem	Fix
YAML duplicate key error	You have two of the same key. Replace the line — don't add a second one
Chrome won't start with debugging	Quit Chrome completely (Cmd+Q) before launching with `--remote-debugging-port`
`EADDRINUSE` on port 9333	`lsof -ti:9333 \| xargs kill`
`502` from tunnel	Relay server isn't running
`Connection refused`	Set `host: "0.0.0.0"` in config if connecting remotely
Dashboard blank	Build the SPA: `cd relay-server/dashboard && bun run build`
`bun: command not found`	`curl -fsSL https://bun.sh/install \| bash`

Built with 🦞 by ag11.dev · GitHub · Privacy