Flux

A real-time peer-to-peer protocol built on Lux.

MCP connects tools to models. Flux connects models to each other.

Any process -- agent, service, script, dashboard -- connects to a single Lux instance and instantly discovers every other peer on the network. No REST APIs between peers. No service URLs. No API keys. Just connect and collaborate.

  Alice                      Lux                       Bob
    |                         |                         |
    |--- join("project") ---->|<--- join("project") ----|
    |                         |                         |
    |--- ctx.set("docs") ---->|                         |
    |                         |---- ctx:updated ------->|  (real-time event)
    |                         |                         |
    |--- send("summarize") -->|                         |
    |                         |--- job pushed --------->|  (routed by capability)
    |                         |<--- result published ---|
    |<-- result returned -----|                         |
    |                         |                         |
    |--- stream("analysis") ->|---- stream:data ------->|  (live tokens)
    |                         |---- stream:data ------->|
    |                         |---- stream:end -------->|

Quick Start

bun add lux-flux

import { Flux } from "lux-flux";

const flux = new Flux({
  url: "lux://10.0.0.176:6379",
  name: "researcher",
});

flux.expose("summarize", async (payload: any) => {
  return summarize(payload.text);
});

await flux.start();

// join a workspace -- scoped collaboration
await flux.join("project-alpha");

// shared context -- any peer can read/write
await flux.ctx.set("project-alpha", "findings", { topics: ["perf", "latency"] });
const docs = await flux.ctx.get("project-alpha", "docs");

// call any peer by capability (auto-routed)
const result = await flux.send("translate", { text: "hello", lang: "es" });

// stream live data to the workspace
await flux.stream("project-alpha", "my-analysis", (async function* () {
  for await (const token of llm.stream("analyze this...")) {
    yield token;
  }
})());

// listen to everything happening
flux.on("peer:joined", (e) => console.log(`${e.peerName} joined`));
flux.on("ctx:updated", (e) => console.log(`${e.peerName} updated ${e.key}`));
flux.onStream(peer.peerId, "reasoning", (chunk) => process.stdout.write(chunk));

Core Concepts

Peers

Any process that connects to Flux. Agents, services, scripts, UIs. They register with a name and capabilities, heartbeat to stay alive, and disappear cleanly when they stop.

Workspaces

Scoped collaboration rooms. Peers join a workspace to work together on something. Events, context, and streams are scoped to workspaces. A peer can be in multiple workspaces.

Shared Context

Key-value state within a workspace. Any peer can read and write. No fetching from each other -- just read the shared memory directly. When context changes, every peer in the workspace gets a real-time event.

Capabilities

Peers advertise what they can do, not where they live. flux.expose("summarize", handler) means "I can summarize." When someone calls flux.send("summarize", data), Flux routes it to a peer with that capability automatically.

Streams

Publish live data that other peers can subscribe to. Token-by-token LLM output, sensor readings, progress updates. Delivered via pub/sub to the entire workspace in real-time.

API

new Flux(config)

Option	Default	Description
url	required	Lux connection (lux://host:port)
name	random	Human-readable peer name
jobTimeout	30000	Timeout in ms for send() calls

Lifecycle

Method	Description
flux.expose(name, handler)	Register a capability. Call before start()
flux.start()	Connect, register, begin consuming jobs
flux.stop()	Deregister, cleanup, disconnect

Workspaces

Method	Description
flux.join(workspace)	Join a workspace, returns current peers
flux.leave(workspace)	Leave a workspace
flux.peers(workspace?)	List peers (in workspace or globally)

Communication

Method	Description
flux.send(fn, payload, timeout?)	RPC to any peer with capability fn
flux.ctx.set(ws, key, value)	Write shared context
flux.ctx.get(ws, key)	Read shared context
flux.ctx.del(ws, key)	Delete shared context
flux.ctx.keys(ws)	List context keys
flux.stream(ws, key, iterable)	Stream data to workspace
flux.onStream(peerId, key, handler)	Subscribe to a peer's stream

Events

Event	Fired when
peer:joined	A peer joins a workspace you're in
peer:left	A peer leaves or disconnects
ctx:updated	Shared context changes
stream:data	Stream chunk received
stream:end	Stream finished

Lux Key Patterns

Key	Type	Purpose
flux:peer:{id}	String + TTL	Peer metadata, expires on missed heartbeat
flux:peers	Set	All active peer IDs
flux:fn:{name}	Set	Peers with a given capability
flux:q:{peerId}	List	Job queue per peer
flux:notify:{peerId}	Pub/Sub	Wake peer when job arrives
flux:res:{peerId}	Pub/Sub	Deliver results back to caller
flux:ws:{name}:peers	Set	Peers in a workspace
flux:ws:{name}:ctx:{key}	String	Shared context within workspace
flux:ws:{name}:events	Pub/Sub	Workspace event channel

License

MIT