Unifying Clawnet: One Protocol for Simpler, Safer Connections

I have spent a lot of time dealing with the headache of maintaining two separate protocol stacks. It is frustrating when you have one system for the control plane and a completely different one for node transport. It leads to messy identity management and situations where security approvals pop up on a headless server in a closet instead of the phone in your hand.

We decided to fix this by moving toward a single, rigorous protocol. This refactor simplifies the architecture and ensures that your identity stays stable across every client, whether you are using the CLI, the macOS app, or a mobile device.

What You’ll Need

• Access to the Gateway WebSocket (control plane) logic in src/gateway/server/ws-connection/message-handler.ts.
• The Bridge node transport logic in src/infra/bridge/server/connection.ts.
• A device capable of generating keypairs to derive a stable deviceId.
• TLS certificates and keys for fingerprint pinning.

Quick Start

You can move to the unified Clawnet protocol by following these steps to transition from the old two-stack model to the new role-based system.

1. Define your role and scope. Every connection now requires a specific role. Choose node if you are hosting capabilities like a camera or screen, or operator if you are controlling the plane.
2. Initiate the unified pairing flow. Connect your client unauthenticated. You must provide a deviceId (hash of your public key), a displayName, and your requested role.
3. Approve the pairing request. The Gateway will create a request that appears on an Operator’s UI. Once approved, the Gateway issues credentials bound to your public key.
4. Connect with TLS pinning. Use the existing TLS runtime from src/infra/bridge/server/tls.ts for your WebSocket connection. This ensures remote traffic is encrypted and verified without relying on external tunnels.

Troubleshooting

Identity Duplication

If you see the same machine appearing twice in your UI (once as a node and once as a UI client), ensure both connections use the same deviceId. The new system merges these entries into a single instance row based on that stable ID.

Approvals Popping Up on the Wrong Device

In the legacy state, approvals were handled by the node host. If your prompt is appearing on a remote node instead of your current screen, you are likely still using the old Bridge flow. Transition to the centralized approval flow where the Gateway routes approval.requested events to all active Operator UIs.

Connection Refused for Admin APIs

If a Node client attempts to call config or session APIs and gets rejected, this is expected behavior. Nodes are restricted to registering capabilities and receiving invoke commands. They cannot access the control plane. Check your operator.admin or operator.write scopes if you need to manage the Gateway.

MITM Risks on Remote Mobile Connections

If you are worried about security on public networks, verify that you have enabled TLS fingerprint pinning. The Gateway advertises its fingerprint in discovery TXT records. Use the verification logic found in src/node-host/bridge-client.ts to pin the connection.

If you hit a wall during the refactor, check out the AI Setup Assistant.

What’s Next

• Gateway Protocol Documentation
• Bridge Protocol Reference
• Client Identity and Keypair Logic
• TLS Runtime Configuration