# claw-relay

Adopt this skill: https://proskills.md/skills/other/andreagriffiths11-claw-relay

Page: https://proskills.md/skills/other/andreagriffiths11-claw-relay
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 5075
upstream: https://github.com/andreagriffiths11/claw-relay/blob/HEAD/SKILL.md

````text
---
name: claw-relay
description: Control a remote browser through Claw Relay. Use when you need to navigate authenticated websites, click buttons, fill forms, take screenshots, or read page content on a user's real browser — especially when the agent runs on a different machine (cloud, container, server) than the browser. Triggers on remote browser control, authenticated browsing, real browser, cookie-based access, browser relay.
---

# Claw Relay — Remote Browser Control

You control a real Chrome browser through a WebSocket relay. The browser runs on the user's machine with their real cookies and sessions. You run anywhere.

## Connection

Connect via WebSocket. Auth first, then send actions.

```javascript
const ws = new WebSocket('wss://<relay-url>');

// First message must be auth
ws.send(JSON.stringify({
  type: 'auth',
  token: '<agent-token>',
  agent_id: '<your-agent-id>'
}));
```

The relay URL and token are provided by the user or set as environment variables:
- `CLAW_RELAY_URL` — WebSocket URL (e.g. `wss://relay.example.com`)
- `CLAW_RELAY_TOKEN` — agent auth token
- `CLAW_RELAY_AGENT` — your agent identifier

## Actions

After auth succeeds, send actions as JSON:

| Action | Scope | Payload |
|--------|-------|---------|
| `snapshot` | `read` | `{"type": "snapshot"}` — returns accessibility tree |
| `screenshot` | `read` | `{"type": "screenshot"}` — returns base64 PNG via WebSocket |
| `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://..."}` |
| `evaluate` | `execute` | `{"type": "evaluate", "js": "document.title"}` |
| `close` | `navigate` | `{"type": "close"}` — closes current tab |

## Responses

```json
{"type": "result", "action": "snapshot", "ok": true, "data": "...accessibility tree..."}
{"type": "result", "action": "screenshot", "ok": true, "data": "<base64-encoded-png>", "mimeType": "image/png"}
{"type": "error", "code": "permission_denied", "message": "Agent lacks 'interact' scope"}
{"type": "error", "code": "site_blocked", "message": "mail.google.com is blocked"}
```

## Workflow Pattern

1. **Snapshot first** — read the page structure before acting
2. **Find elements by ref** — the accessibility tree assigns refs (e.g. `e1`, `e5`) to interactive elements
3. **Act on refs** — click, type, fill using the ref from the snapshot
4. **Snapshot again** — verify the page changed as expected
5. **Repeat** — navigate → snapshot → act → verify

```
snapshot → find button ref → click ref → snapshot → verify
```

## Scopes (least privilege)

Request only what you need:

- **`read`** — snapshot, screenshot. Start here.
- **`interact`** — click, type, fill, hover, select. Adds the ability to change things.
- **`navigate`** — go to URLs. Can access any allowed site as the logged-in user.
- **`execute`** — run JavaScript on the page. Nuclear option. Avoid unless necessary.

## Security Constraints

- **Allowlist** — your agent can only access sites explicitly allowed in its config
- **Blocklist** — banking, email, and auth providers are always blocked regardless of allowlist
- **Rate limiting** — actions are rate-limited per agent (token bucket)
- **Audit log** — every action is logged with timestamps, agent ID, action, target, and result

## What Makes This Different

Local browser tools require agent and browser on the same machine. Claw Relay doesn't. Your agent runs anywhere — cloud, server, container — and controls the user's real browser remotely. Real cookies, real sessions, real logins. No headless browser, no fake profiles.

## Setup

Users set up the relay on their machine:

```bash
npx @acolombiadev/claw-relay
```

This launches Chrome, generates config with random tokens, and starts the relay. One command, zero setup.

## Common Tasks

### Read a page
```json
{"type": "navigate", "url": "https://github.com/notifications"}
// wait for response
{"type": "snapshot"}
```

### Fill and submit a form
```json
{"type": "snapshot"}
// find input ref from tree, e.g. e3
{"type": "fill", "ref": "e3", "text": "search query"}
{"type": "press", "key": "Enter"}
```

### Click a button
```json
{"type": "snapshot"}
// find button ref, e.g. e7
{"type": "click", "ref": "e7"}
```

## Error Handling

- `permission_denied` — you lack the required scope. Ask the user to upgrade your agent config.
- `site_blocked` — the site is on the global blocklist (cannot be overridden) or not in your allowlist. Ask the user to check the config.
- `rate_limited` — slow down. Wait and retry.
- `engine_error` — browser or CDP issue. The page may have navigated or the element may be stale. Re-snapshot and retry.
````

## File: README.md
upstream: https://github.com/andreagriffiths11/claw-relay/blob/HEAD/README.md

````text
<p align="center">
  <img src="assets/logo.png" alt="Claw Relay" width="300">
</p>

# Claw Relay

Give your AI agents a real browser.

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/claw-relay?referralCode=a2vuTz&utm_medium=integration&utm_source=template&utm_campaign=generic)

## Quick Start

```bash
npx @acolombiadev/claw-relay
```

Launches a dedicated Chrome window, starts the relay, generates config with random tokens. One command, zero setup.

**First time:** Sign into GitHub (or any site) in the Claw Relay Chrome window. Logins persist between restarts.

**Restart:** `Ctrl+C` stops the relay. Chrome stays open. Run `npx @acolombiadev/claw-relay` again — it reconnects without relaunching Chrome.

## What It Does

Claw Relay sits between your AI agent and Chrome. The agent sends actions (navigate, click, read) via WebSocket — the relay enforces auth, permissions, rate limits, and site restrictions before forwarding to Chrome via CDP.

### Capabilities

- **Navigation & snapshots** — browse pages, read accessibility trees
- **Element interaction** — click, type, fill, hover, select, drag & drop
- **Screenshots** — full page, viewport, or individual elements
- **Batch actions** — execute multiple actions in a single message
- **Tab targeting** — pin actions to specific tabs via `targetId`
- **Wait conditions** — wait for text, selectors, navigation, network idle, or custom JS
- **Console & network monitoring** — capture logs and requests
- **PDF generation** — render pages to PDF
- **Viewport resize** — test responsive layouts
- **JavaScript evaluation** — run arbitrary code in page context

## Connect Your Agent

Works with **Copilot CLI**, **OpenClaw**, **Claude Code**, **nanobot**, **ZeroClaw**, or any MCP client.

### MCP (Copilot CLI, Claude Code, any MCP client)

```json
{
  "mcpServers": {
    "claw-relay": {
      "command": "node",
      "args": ["mcp/claw-relay-mcp.js"],
      "env": {
        "CLAW_RELAY_URL": "ws://localhost:9333",
        "CLAW_RELAY_TOKEN": "your-token",
        "CLAW_RELAY_AGENT": "default"
      }
    }
  }
}
```

### OpenClaw Skill (OpenClaw, nanobot, ZeroClaw)

Use the bundled CLI client — no MCP required:

```bash
export CLAW_RELAY_URL="ws://localhost:9333"
export CLAW_RELAY_TOKEN="your-token"
export CLAW_RELAY_AGENT="your-agent"

node skills/openclaw/relay-client.cjs navigate https://github.com
node skills/openclaw/relay-client.cjs snapshot
node skills/openclaw/relay-client.cjs click e3
```

See [`skills/openclaw/SKILL.md`](skills/openclaw/SKILL.md) for the full agent skill reference.

### WebSocket (custom agents)

Connect directly via WebSocket for full control:

```javascript
const ws = new WebSocket('ws://localhost:9333');
ws.send(JSON.stringify({ type: 'auth', token: 'your-token', agent_id: 'your-agent' }));
```

See [protocol docs](docs/protocol.md) for the full action reference.

See [MCP docs](docs/mcp.md) for MCP-specific setup.

## Chrome Extension

Optional — lets your agent use your normal Chrome instead of the dedicated window:

1. Install from the [Chrome Web Store](https://chromewebstore.google.com/detail/claw-relay/jkididiajaipgoochodhlgkdhganebfp)
2. Click the toolbar icon on any tab to share it with the relay

> **For development:** `chrome://extensions` → Developer mode → Load unpacked → select `extension/`

## Configuration

Auto-generated `config.yaml` on first run. Or copy the example manually:

```bash
cp relay-server/config.example.yaml relay-server/config.yaml
```

Key settings:

```yaml
agents:
  my-agent:
    token: "crly_..."           # auth token
    scopes: ["read", "navigate", "interact"]
    allowlist: ["github.com"]   # where the agent can go
    rateLimit: 30               # actions per minute

blocklist:
  - "*.bank.com"               # always blocked
```

## CLI Options

```
npx @acolombiadev/claw-relay [options]

  --port <number>    Server port (default: 9333)
  --config <path>    Custom config path
  --no-chrome        Skip Chrome launch (assumes CDP on :9222)
```

## Security

- **Auth** — token + agent ID per connection
- **Scopes** — read, navigate, interact, execute
- **Allowlist/Blocklist** — per-agent URL restrictions
- **Rate limiting** — per agent, per minute
- **Audit log** — every action logged with timestamp

## First-Time Agent Setup

> **💡 Quickest setup with GitHub Copilot CLI:**
> ```bash
> copilot --additional-mcp-config '{"mcpServers":{"claw-relay":{"command":"node","args":["mcp/claw-relay-mcp.js"],"env":{"CLAW_RELAY_URL":"ws://localhost:9333","CLAW_RELAY_TOKEN":"your-token","CLAW_RELAY_AGENT":"your-agent-id"}}}}'
> ```
> That's it — Copilot CLI loads the MCP server and you're ready to browse. [Get Copilot CLI free →](https://docs.github.com/en/copilot/github-copilot-in-the-cli)

1. Add your agent to `config.yaml` with a token, scopes, and allowlist
2. Restart the relay (config is read at startup)
3. Connect using your platform's method (MCP or OpenClaw skill)
4. Test with a simple `snapshot` action

**Common gotchas:**

- **Agent ID is case-sensitive** — `Rusty` ≠ `rusty`. Match `config.yaml` exactly.
- **Restart after config changes** — the relay reads `config.yaml` at startup only
- **Check scopes** — if an action fails with "permission_denied", the agent needs that scope added
- **One action per call** (OpenClaw skill) — don't try to batch or keep connections open

## Docs

| | |
|---|---|
| [Setup Guide](docs/setup.md) | Install, configure, launch |
| [MCP Server](docs/mcp.md) | Connect MCP clients |
| [Protocol](docs/protocol.md) | WebSocket API reference |
| [Dashboard](docs/dashboard.md) | Web UI for monitoring |
| [Tunnels](docs/tunnels.md) | Remote access |
| [Troubleshooting](docs/troubleshooting.md) | Common issues |
| [Responsible Use](docs/responsible-use.md) | When to use Claw Relay (and when not to) |

## Agent Skills

Drop-in skill files that teach AI agents how to use Claw Relay:

| | |
|---|---|
| [Browser Skill](skills/browser/SKILL.md) | Teaches any agent to navigate, click, type, screenshot — works with any framework |
| [OpenClaw Skill](skills/openclaw/SKILL.md) | Standalone relay client for OpenClaw, nanobot, ZeroClaw (no MCP required) |

Copy the relevant `SKILL.md` into your agent's skills directory, or point your agent at the file directly.

## Built With

- [Node.js](https://nodejs.org) — runtime
- [Hono](https://hono.dev) — HTTP framework
- [Playwright](https://playwright.dev) — browser automation
- [Cloudflare Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) — secure remote access
- [TanStack Router](https://tanstack.com/router) — dashboard SPA

## License

MIT
````
