Openclaw Local Bridge Protocol Spec

# OpenClaw Local Bridge Protocol Spec

Status: Draft  
Date: 2026-03-10  
Related: [openclaw-web-technical-architecture.md](./openclaw-web-technical-architecture.md), [../pi_agent_rust/docs/rpc.md](../pi_agent_rust/docs/rpc.md)

## 1. Purpose

Define the protocol between the web control plane and the local OpenClaw bridge.

The bridge is a local daemon/process that:

- authenticates the user device with the control plane
- owns the session to the local `pi_agent_rust` runtime
- converts control-plane commands into Pi RPC messages
- streams runtime status back to the web product

## 2. Trust Boundary

The bridge is trusted to:

- prove device identity
- manage the local runtime process
- enforce local permission prompts
- upload only policy-allowed metadata and artifacts

The bridge is not trusted to:

- self-assign workspace access
- bypass per-system launch restrictions
- retain long-lived unscoped control-plane credentials

## 3. Transport

### 3.1 Control-plane to bridge

- HTTPS for registration, token refresh, artifact upload negotiation, and command polling or websocket upgrade
- preferred steady-state transport: WebSocket

### 3.2 Bridge to runtime

- local stdio JSONL RPC using `pi_agent_rust --mode rpc`

## 4. Main Objects

### 4.1 Device

```json
{
  "deviceId": "dev_123",
  "workspaceId": "ws_123",
  "label": "Lu MacBook Pro",
  "platform": "macos",
  "runtimeVersion": "pi_agent_rust@0.1.8",
  "status": "online"
}
```

### 4.2 Bridge session

```json
{
  "sessionId": "bs_123",
  "deviceId": "dev_123",
  "issuedAt": "2026-03-10T02:00:00Z",
  "expiresAt": "2026-03-10T14:00:00Z",
  "scopes": ["device:heartbeat", "task:execute", "artifact:upload"]
}
```

### 4.3 Linked system policy

```json
{
  "systemId": "sys_123",
  "syncMode": "metadata_only",
  "remoteLaunchAllowed": true,
  "cloudReadLocalArtifacts": false
}
```

## 5. Linking Flow

1. authenticated web user requests a link challenge
2. control plane returns `challengeId`, `code`, and expiry
3. local bridge redeems the challenge
4. control plane creates `deviceId` and bridge session
5. bridge starts heartbeat and capability report

## 6. Runtime Attachment Flow

1. bridge starts `pi_agent_rust --mode rpc`
2. bridge sends `get_state`
3. bridge records runtime capabilities and active session info
4. bridge marks runtime as ready

## 7. Command Flow

### 7.1 Web launch request

```json
{
  "commandId": "cmd_123",
  "type": "task.launch",
  "taskRunId": "run_123",
  "systemId": "sys_123",
  "payload": {
    "message": "Build the landing page hero section",
    "streamingBehavior": "follow-up"
  }
}
```

### 7.2 Bridge to Pi RPC

```json
{
  "id": "cmd_123",
  "type": "prompt",
  "message": "Build the landing page hero section",
  "streamingBehavior": "follow-up"
}
```

### 7.3 Event uplink

```json
{
  "deviceId": "dev_123",
  "taskRunId": "run_123",
  "event": {
    "type": "text_delta",
    "data": "Starting with the page structure..."
  }
}
```

## 8. Heartbeat

Heartbeat interval target: 15 seconds.

Payload:

```json
{
  "deviceId": "dev_123",
  "status": "online",
  "queueDepth": 0,
  "activeRuns": 1,
  "cpuPercent": 12,
  "memoryMb": 284,
  "lastRpcHealth": "ok",
  "timestamp": "2026-03-10T02:15:00Z"
}
```

## 9. Permission Rules

- remote task launch is denied unless the system policy allows it
- artifact upload is denied when system sync mode is `local_only`
- bridge must request local confirmation before first remote launch for a system unless the user opted into persistent approval

## 10. Failure Modes

- runtime unavailable: bridge reports `runtime_unavailable`
- bridge offline: control plane marks device offline after heartbeat timeout
- command timeout: orchestration worker marks run `stalled` and exposes retry controls
- revoked session: bridge must stop processing commands and require relink

## 11. Security Requirements

- bridge session tokens are short-lived
- refresh tokens are device-bound and revocable
- all control-plane payloads are signed or authenticated
- secrets never enter Pi session transcripts
- logs redact tokens, challenge codes, and provider credentials

## 12. First Implementation Scope

- code-based device linking
- websocket session from bridge to control plane
- task launch, status events, and artifact metadata upload
- no remote filesystem browsing
- no arbitrary shell relay from the control plane