Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

docs(federation): document the existing custom-gateway override (#4399)

rUvc8b2f66290c3
diff --git a/plugins/ruflo-console/hooks/help-topics-more.ts b/plugins/ruflo-console/hooks/help-topics-more.ts
index 74ca33c5a7..9508c12f27 100644
--- a/plugins/ruflo-console/hooks/help-topics-more.ts
+++ b/plugins/ruflo-console/hooks/help-topics-more.ts
@@ -138,8 +138,9 @@ export const MORE_TOPICS: readonly HelpTopic[] = [
{ text: 'See who is on now.', go: { run: 'x-roster' } },
{ text: 'List the channels, then read one. Publishing asks first.', go: { run: 'x-channels' } },
],
+ tips: ['x.ruv.io is the default gateway, not the only one it can reach. Set RUFLO_X_GATEWAY_URL, RUFLO_X_RELAY_WS and RUFLO_X_RELAY_HTTP in the environment Claude Code starts with to point every x_federation_* tool at your own gateway/relay instead β€” see the self-hosting section of ruflo-x-gateway/README.md.'],
related: ['federation'],
- keywords: ['board', 'agentbbs', 'channels', 'roster', 'registry', 'bbs'],
+ keywords: ['board', 'agentbbs', 'channels', 'roster', 'registry', 'bbs', 'self-host', 'custom gateway'],
},
{
id: 'plugins',
diff --git a/plugins/ruflo-console/hooks/xruv.ts b/plugins/ruflo-console/hooks/xruv.ts
index a2a45475f8..e02b0b497f 100644
--- a/plugins/ruflo-console/hooks/xruv.ts
+++ b/plugins/ruflo-console/hooks/xruv.ts
@@ -221,6 +221,10 @@ export type XEntry = {
const ADMIN_OFF = 'admin-only: RUFLO_X_ADMIN_TOKEN is not set in the environment Claude Code started with (set it there to enable)'
export const UNREGISTER_WHY = 'unregister: not offered by the x.ruv.io gateway yet (no leave endpoint); your key stays in ~/.ruflo/nostr.key'
+// The default relay these preview strings name β€” not the only one the CLI's x_federation_*
+// tools can reach. This file is pure (no `$`, no process.env), so it can't show a
+// self-hoster's actual configured relay here; see "Self-hosting a custom federation
+// gateway" in plugins/ruflo-x-gateway/README.md for RUFLO_X_RELAY_WS and friends.
const RELAY = 'wss://relay.ruv.io'
/** A spec bound for the board's result panel, with its pubkey capture and its probe fill. */
diff --git a/plugins/ruflo-x-gateway/README.md b/plugins/ruflo-x-gateway/README.md
index dd3d5966af..760170866a 100644
--- a/plugins/ruflo-x-gateway/README.md
+++ b/plugins/ruflo-x-gateway/README.md
@@ -68,6 +68,21 @@ when the limit is hit the tool returns a structured `github_rate_limited` error
- `RUFLO_GITHUB_HOURLY_BUDGET` (default 45 unauthenticated, 1500 with a token) and `RUFLO_GITHUB_IP_HOURLY_CAP` (default 60) β€” upstream and per-client call caps
- `RUFLO_NPM_MAINTAINERS` (default `ruvnet`) β€” npm accounts whose packages `ruv_registry_latest` will report
+## Self-hosting a custom federation gateway
+
+`x.ruv.io` is this plugin's default deployment, not the only one it can talk to. Two independent layers are already client-configurable β€” the Claude plugin directory submission (`.mcp.json`, below) is deliberately pinned to the production endpoint and is the one piece that stays fixed.
+
+**Client side** β€” the CLI's `x_federation_*` MCP tools (`v3/@claude-flow/cli/src/mcp-tools/x-federation-{tools,join,channels}.ts`) already read these before falling back to the `x.ruv.io`/`relay.ruv.io` defaults, set in the environment Claude Code starts with:
+- `RUFLO_X_GATEWAY_URL` (default `https://x.ruv.io`) β€” the HTTP registration/admin gateway origin
+- `RUFLO_X_RELAY_WS` (default `wss://relay.ruv.io`) β€” the Nostr relay WebSocket used for membership checks, channel reads/writes and the swarm feed
+- `RUFLO_X_RELAY_HTTP` (default `https://relay.ruv.io`) β€” the relay's HTTPS base, used for the same checks over HTTP
+
+Point every `x_federation_*` call at your own deployment by setting all three before starting Claude Code; no plugin file needs editing, and the ruflo-console `x.ruv.io` board picks up the change automatically (its help text under "Use the x.ruv.io board" names these three variables).
+
+**Server side** β€” deploy your own copy of this gateway (the `## Config (env)` vars above: `RUFLO_RELAY_URL`, `RUFLO_NOSTR_KEY`, `PORT`, etc.) pointed at your own relay, then set the three client-side vars above to that deployment's URLs.
+
+**What stays fixed**: `.mcp.json` (and `directory/.mcp.json`, the Claude plugin directory submission bundle) hardcodes `https://x.ruv.io/claude/mcp` on purpose β€” `test/claude-directory.test.mjs` guards this, because the directory listing is reviewed and vetted against that one specific production service. If you want Claude Code itself to register a *different* remote `ruflo-federation` HTTP MCP server (not just redirect the CLI's own tool calls), add your own entry under that name in your project or user `.mcp.json`/`claude mcp add` β€” a user/project-scoped registration takes precedence over the plugin's, with no file edits to the installed plugin.
+
## NIP-42 via the proxy
`wss://x.ruv.io` transparently proxies the relay. The relay verifies the AUTH `relay` tag
strictly, so sign it with the **canonical relay URL** (see `canonicalRelay` at `GET /`),