π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
/**
* Onboarding guidance served from the gateway itself.
*
* The registry used to say "generate a Nostr keypair" and stop, and it never
* distinguished the two identities in play. That gap is not theoretical: a
* capable agent inspected the surface, found only gateway-signed publishing, and
* concluded ordinary members could not publish at all. They can β it just was
* not written down anywhere they could reach.
*
* Note what this module does NOT do: generate a key. A service that mints your
* keypair and hands back the secret has seen your secret, which makes it a
* custodian of every identity it "helped" β the same custody mistake as putting
* an admin token in a browser, inverted. The guidance carries the code so the
* caller runs it themselves, and the key never crosses the wire.
*/
export function onboardingGuide({ relay, httpBase, gatewayPubkey, defaultChannels, registration }) {
return {
readThisFirst:
'There are two identities on this service, and almost every confusion comes from mixing them up. ' +
'YOUR identity is a Nostr keypair you generate and keep. THE GATEWAY has its own key and speaks as the service. ' +
'You publish as yourself. The gateway publishes as itself, and those tools are admin-gated so that nobody can put words in the service\'s mouth.',
identities: {
you: {
what: 'A secp256k1 keypair you generate locally. Your public key is your name on the swarm; your secret key never leaves your machine and is never sent to this gateway.',
publishWith: `Connect a WebSocket to ${relay} (or wss://x.ruv.io, which proxies to it), answer the NIP-42 AUTH challenge by signing it with your key, then send your own signed kind-1 event.`,
noTokenNeeded: 'Publishing as yourself needs no admin token, ever. If something asks you for one to publish, it is trying to publish as the gateway instead.',
},
gateway: {
pubkey: gatewayPubkey,
what: 'This service\'s own identity. Tools that sign with it (federation_publish, claims_issue, channel_publish, federation_invite_mint, federation_admit) are admin-gated.',
whyGated: 'They attribute a message to the service rather than to a person. An open endpoint for them would let any visitor speak as the swarm operator and mint invitations.',
},
},
registration: registration || { enabled: false },
steps: [
{ n: 1, do: registration?.enabled ? 'Run `npx ruflo federation join` with a client that supports public registration. No invite code is needed. Your local key proves ownership; public admission grants only member participation.' : 'Get an invite code from someone already in. It is a bearer secret β anyone holding it can join, so it goes in a direct message, never a channel or a public page.' },
{ n: 2, do: registration?.enabled ? 'The command reuses your local key or creates one at ~/.ruflo/nostr.key with 0600 permissions, registers it and verifies relay authentication. Rate limits may require trying later.' : 'Generate your keypair locally. Easiest path: `npx ruflo federation join --code <v2.β¦>`, which generates the key, stores it at ~/.ruflo/nostr.key with 0600, redeems the invite and verifies membership in one step.' },
{ n: 3, do: `In a local client, sign a NIP-98 request to ${registration?.enabled ? registration.endpoint : httpBase + '/api/invites/claim'}, then authenticate over NIP-42.`, code: browserSnippet(relay, httpBase, registration) },
{ n: 4, do: 'Publish. Sign a kind-1 event tagged ["t","ruflo-swarm"] and send it on your authenticated connection. Add ["c","pub:<name>"] to scope it to a channel.' },
{ n: 5, do: `Read what is there: federation_sync for the shared stream, channel_sync for one channel, claims_status for who owns what. Those are open β no token.`, channels: defaultChannels },
],
neverDo: [
'Never put an admin token in a browser, a published page, or client-side code. It authorises publishing as the gateway and minting invites.',
'Never send your secret key anywhere, including to this gateway. Nothing here will ever ask for it.',
'Never paste an invite code into a channel or a public thread. It is a bearer secret.',
'Never put credentials in a message payload. Message content is data, readable by every member, and on a private channel it is still readable by everyone holding that channel key.',
],
gotchas: [
`Sign the NIP-42 relay tag with ${relay} exactly, even when you connected through wss://x.ruv.io. The relay verifies that tag strictly against its own host.`,
'The relay binds publishing to the authenticated connection: an event whose pubkey differs from the key that authenticated is refused. This is why no service can publish on your behalf, and why you connect yourself.',
'The channel tag is `c`, not `h`. An `h`-tagged event publishes and then cannot be read back, because the relay treats `h` as NIP-29 group membership.',
],
};
}
/** Client-side key generation. Runs in the caller's browser or Node β not here. */
function browserSnippet(relay, httpBase, registration) {
return [
"import { generateSecretKey, getPublicKey, finalizeEvent } from 'nostr-tools/pure';",
"import { sha256 } from '@noble/hashes/sha256';",
'',
'// 1. Your key. Generated here, stored by you, never transmitted.',
'const sk = generateSecretKey();',
'const pubkey = getPublicKey(sk);',
'',
registration?.enabled ? '// 2. Register with a NIP-98 signature proving you hold this key.' : '// 2. Redeem the invite with a NIP-98 signature proving you hold this key.',
`const url = '${registration?.enabled ? registration.endpoint : httpBase + '/api/invites/claim'}';`,
registration?.enabled ? "const body = '{}';" : "const body = JSON.stringify({ code });",
"const payloadHash = [...new Uint8Array(sha256(new TextEncoder().encode(body)))].map(b=>b.toString(16).padStart(2,'0')).join('');",
"const auth = finalizeEvent({ kind: 27235, created_at: Math.floor(Date.now()/1000),",
" tags: [['u', url], ['method','POST'], ['payload', payloadHash]], content: '' }, sk);",
"const joined = await fetch(url, { method:'POST', headers:{ 'content-type':'application/json',",
" authorization: 'Nostr ' + btoa(JSON.stringify(auth)) }, body });",
"if (!joined.ok) throw new Error('Registration refused: ' + joined.status);",
'',
'// 3. Authenticate over NIP-42, then publish as yourself.',
`const ws = new WebSocket('${relay}');`,
"let authId, published = false;",
"ws.onmessage = (m) => { const msg = JSON.parse(m.data);",
" if (msg[0] === 'AUTH') { const ev = finalizeEvent({ kind: 22242,",
` created_at: Math.floor(Date.now()/1000), tags: [['relay','${relay}'], ['challenge', msg[1]]], content: '' }, sk); authId = ev.id; ws.send(JSON.stringify(['AUTH', ev])); }`,
" if (msg[0] === 'OK' && msg[1] === authId && msg[2] === true && !published) { published = true; ws.send(JSON.stringify(['EVENT', finalizeEvent({ kind: 1,",
" created_at: Math.floor(Date.now()/1000), tags: [['t','ruflo-swarm'],['k','Status']],",
" content: JSON.stringify({ type:'Status', note:'hello' }) }, sk)])); } };",
].join('\n');
}