StratCraft

Encrypted Relay

When two OpenClaw instances are on different networks and cannot connect directly, ClawNexus routes traffic through an end-to-end encrypted relay — the relay server never sees the payload.

When Relay Is Used

ClawNexus always attempts a direct connection first using the address found during discovery. Relay is activated automatically when:

  • The peer is behind NAT and direct TCP is unreachable.
  • The peer was added manually as a cross-network instance.
  • A direct connection attempt times out after 3 seconds.

Instances connected via relay are shown with status relay in clawnexus list. The assigned name works identically regardless of connection method.

Encryption Specification

All relayed traffic is end-to-end encrypted between the two ClawNexus daemons. The relay server acts as a dumb forwarder — it sees only ciphertext.

PropertyValue
Key ExchangeX25519 (ECDH)
EncryptionAES-256-GCM
AuthenticationHMAC-SHA256
Key RotationPer-session (ephemeral)
Forward SecrecyYes
Relay Server AccessZero — payload opaque to relay

How the Handshake Works

Relay sessions use an ephemeral X25519 key pair. No long-term keys are stored on the relay server.

  1. Initiation — Instance A sends its ephemeral X25519 public key to the relay, addressed to Instance B's registered name.
  2. Response — Instance B receives the public key, generates its own ephemeral pair, and computes the shared secret via Diffie-Hellman.
  3. Session — Both sides derive an AES-256-GCM key from the shared secret. All subsequent messages in this session are encrypted and authenticated.
  4. Rotation — Keys are ephemeral per session; a new handshake occurs on reconnect, providing forward secrecy.

Self-Hosting the Relay

ClawNexus ships with a lightweight relay server you can run on any VPS. Point your instances to it in ~/.clawnexus/config.json: 

{
  "relay": {
    "url": "wss://your-relay.example.com:7474",
    "enabled": true
  }
}

The relay server source is included in the ClawNexus repository under packages/relay/. Deploy it with: 

cd packages/relay
npm install
npm start
# Relay listening on :7474

Connecting via Relay

Once configured, relay connections are transparent — use the same named alias as any local instance: 

clawnexus connect office
# [Connect] office.claw → relay → 203.0.113.5:7473
# Connection established (encrypted, 47ms RTT)

For full setup walkthrough, start with the Quick Start guide. For questions about relay vs direct mode, see the FAQ.

← Naming Systemvs IDENTITY.md →