Yonexus

Yonexus is a cross-instance communication system for OpenClaw built as three separate repositories:

Repository	Role
Yonexus	Umbrella — architecture, planning, and coordination
Yonexus.Server	Central hub plugin — accepts client connections, handles pairing/authentication
Yonexus.Client	Client plugin — connects to server, manages local identity
Yonexus.Protocol	Shared protocol specification — referenced as a submodule by both Server and Client

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

Yonexus.Protocol

Shared protocol specification repository. Both Yonexus.Server and Yonexus.Client reference this as a submodule at protocol/.

---

Repository Structure

Yonexus (umbrella)
├── Yonexus.Protocol  ← shared protocol submodule
├── Yonexus.Server    ← server plugin submodule
│   └── protocol/     ← points to Yonexus.Protocol
└── Yonexus.Client    ← client plugin submodule
    └── protocol/     ← points to Yonexus.Protocol

---

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 Repository Spec Files

Umbrella (Yonexus)

• PLAN.md — project plan and architecture
• ARCHITECTURE.md — architecture overview and repository graph
• FEAT.md — implementation feature checklist

Protocol (Yonexus.Protocol)

• PROTOCOL.md — shared communication protocol specification

Server (Yonexus.Server)

• PLAN.md — server-specific implementation plan
• protocol/ — submodule pointing to Yonexus.Protocol

Client (Yonexus.Client)

• PLAN.md — client-specific implementation plan
• protocol/ — submodule pointing to Yonexus.Protocol

---

Planned TypeScript APIs

Yonexus.Server

sendMessageToClient(identifier: string, message: string): Promise<void>
registerRule(rule: string, processor: (message: string) => unknown): void

Yonexus.Client

sendMessageToServer(message: string): Promise<void>
registerRule(rule: string, processor: (message: string) => unknown): void

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

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

---

Repository URLs

• Yonexus (umbrella)
• Yonexus.Server
• Yonexus.Client
• Yonexus.Protocol