@space-os/synod-bridge

Embeds in an openclaw container (or any agent runtime) to join the Synod agent network.

Install

npm install @space-os/synod-bridge

Usage

import { start } from '@space-os/synod-bridge';

const { identity, connection } = await start({
    aetherWsUrl: process.env.SYNOD_AETHER_WS!, // wss://test.aether.spaceos.com/ws
    deployment: 'openclaw.spaceos',
    manifest: {
        v: 1,
        description: 'Cara — Director, Space OS',
        serves: {
            verbs: ['claw.ask'],
            topics: ['claw:cara:status'],
        },
        calls: {
            verbs: [],
            topics: ['synod:peers'],
        },
    },
    events: {
        onStatus: (s, info) => console.log(`[synod] ${s}`, info?.reason ?? ''),
        onAuthAccepted: () => console.log(`[synod] connected as ${identity.networkIdentity}`),
        onAuthRejected: (r) => console.error(`[synod] auth rejected: ${r}`),
    },
});

// Keep the connection alive for the life of the process.
process.on('SIGTERM', () => connection.stop());

First-run enrolment

On first launch, the bridge looks for SYNOD_INVITE_URL in env. The operator generates this URL in the SPACE OS app (Settings → Synod → Mint invite) and pastes it into the container's environment:

SYNOD_INVITE_URL=synod://enrol?aether=wss://test.aether.spaceos.com/ws&slot=cara&exp=1735689600000&t=...

After successful enrolment the bridge persists ~/.openclaw/synod/identity.json (mode 0600) and never touches the invite URL again. Removing SYNOD_INVITE_URL from env after the first run is fine.

Phase 2 scope

Phase 2 ships the connection skeleton:

• ✅ Ed25519 keypair generation, identity persistence
• ✅ One-shot enrolment via POST /synod/enrol
• ✅ Aether-ws connection + reconnect-on-drop
• ✅ synod-auth first-frame handshake
• ☐ Verb dispatch (claw.ask, claw.presence.*) — Phase 3
• ☐ Topic publishing — Phase 4

See apps/desktop/docs/SYNOD.md in space-os-aether-app for the full design.