Yonexus/README.md

Yonexus

Yonexus is a cross-instance communication system for OpenClaw built as two separate plugins:

• Yonexus.Server
• Yonexus.Client

It is designed for scenarios where one OpenClaw instance acts as a central communication hub and multiple other OpenClaw instances connect to it as clients.

Overview

Yonexus.Server

Installed on the central OpenClaw instance.

Responsibilities:

• run the WebSocket server
• maintain the client registry
• handle pairing and authentication
• track heartbeat and liveness state
• relay messages to connected clients
• rewrite inbound client messages before rule dispatch
• notify a human administrator of pairing requests via Discord DM

Yonexus.Client

Installed on follower OpenClaw instances.

Responsibilities:

• connect to Yonexus.Server
• manage local keypair and shared secret
• complete pairing with out-of-band pairing code
• authenticate on reconnect
• send periodic heartbeat
• send messages to server
• receive messages from server via rule dispatch

---

Architecture

A Yonexus network contains:

• exactly one OpenClaw instance running Yonexus.Server
• one or more OpenClaw instances running Yonexus.Client

Topology rules:

• Yonexus.Server must be reachable via a stable address
• Yonexus.Client instances connect outbound to the server
• direct client-to-client sockets are not required in v1
• client-to-client communication, if needed, is relayed by the server

---

Security Model

Pairing is intentionally out-of-band.

When a new client needs pairing:

• the server generates a pairing code
• the server sends that pairing code by Discord DM to a configured human admin
• the pairing code is not sent over the Yonexus WebSocket connection
• the human relays the code to the client side manually
• the client submits the code back through the protocol

After pairing:

• the server issues a shared secret
• the client stores its private key and secret locally
• reconnect authentication uses signed proof derived from secret + nonce + timestamp

---

Current Spec Files

This repository currently contains planning/spec-first documents:

• PLAN.md — project plan and architecture
• PROTOCOL.md — builtin WebSocket protocol details
• FEAT.md — implementation feature checklist

---

Planned Plugin Manifests

This repo is expected to define separate plugin manifests for:

• plugin.server.json
• plugin.client.json

These represent the initial config surface for Yonexus.Server and Yonexus.Client.

---

Planned TypeScript APIs

Yonexus.Server

• sendMessageToClient(identifier: string, message: string)
• registerRule(rule: string, processor: (message: string) => unknown)

Yonexus.Client

• sendMessageToServer(message: string)
• registerRule(rule: string, processor: (message: string) => unknown)

Message format:

${rule_identifier}::${message_content}

Reserved rule:

builtin

---

Planned Server Config

{
  "followerIdentifiers": ["client-a", "client-b"],
  "notifyBotToken": "<discord-bot-token>",
  "adminUserId": "123456789012345678",
  "listenHost": "0.0.0.0",
  "listenPort": 8787,
  "publicWsUrl": "wss://example.com/yonexus"
}

Planned Client Config

{
  "mainHost": "wss://example.com/yonexus",
  "identifier": "client-a",
  "notifyBotToken": "<discord-bot-token>",
  "adminUserId": "123456789012345678"
}

---

Status

Current repository status:

• planning/specification stage
• split-plugin architecture defined
• protocol draft defined
• implementation not started yet

---

Next Steps

Recommended next deliverables:

• plugin manifests
• source tree scaffolds for server/client
• protocol model types
• transport skeleton
• pairing/auth flow implementation