ensemble
what humds make together when they cooperate
ensemble is the optional mesh layer of hum. One humd hosts many
hums; the ensemble is the network of humds that have chosen to
cooperate. This crate owns the daemon-native shape that survives
across every trust tier, from your two laptops on the same LAN to
autonomous agents finding each other on the open internet.
A single humd works without ever loading ensemble. Solo bees, single-machine agents, and local development don’t need any of this. ensemble matters only when two or more humds need to talk.
It sits in a tight three-layer stack:
nestlers ← humans, agents, plugins, HTTP frontends │ thrum tones (JSON over NDJSON) ▼humd ← per-machine daemon: admission, routing, MCP, drone │ ensemble routing (this crate) ▼peer transport ← InMemory · TCP · TLS · Iroh (QUIC + Noise)The protocol stays the same at every layer. The wire underneath swaps without anything above noticing.
The crate can carry more than the daemon currently drives. Two sections keep that difference visible: what the daemon wires up and not here yet.
Where ensemble fits
A hum is a conversation: state with an identity. A humd is a
daemon that hosts hums. A nestler is a process that uses a humd
(an OC plugin, a CLI client, an autonomous agent). When nestlers on
the same humd talk, they’re already on thrum. When nestlers on
different humds need to talk, that’s ensemble.
| problem | what ensemble gives you |
|---|---|
| where does the conversation live? | content-addressable Hid (sha256 of Ed25519 pubkey). Hums roam between humds without changing identity. |
| how does humd A reach humd B? | Transport trait + a peers.json of known addresses, or kad_find(target) for discovery among peers already known. |
| how do messages flow? | chi:"prompt" / chi:"unfurl" / chi:"wilt" between humds via route(tone) (unicast) or publish(topic, …) (gossip). |
| how do you trust a stranger? | Ed25519-signed hello handshake. Hid = hash(pubkey), so the signature proves identity. |
| who handles NAT, firewalls, dynamic IPs? | IrohTransport, which is QUIC + Noise + hole-punching via the public n0 relay mesh. The daemon binds with bind_with_key_on(): each humd keeps a home relay and publishes it under its node id through n0’s DNS, so a humd behind NAT is dialled by its iroh: hint alone. An iroh-relay: hint skips the lookup. |
Nothing in ensemble knows about models, MCP, JSONL, plugins, or
billing. Those live in humd and hives. This crate is purely
“how do humds find each other and exchange tones.”
The four tiers
| tier | trust | discovery | transport | example |
|---|---|---|---|---|
| T1 own-devices | implicit (you own all) | static peers.json | InMemoryEndpoint (tests) or TcpEndpoint (LAN) | laptop ↔ phone roam |
| T2 trusted-group | pre-shared (team, family) | static + fingerprint pinning | TlsTcpEndpoint with pinned-fingerprint verifier | co-pilot session, 2-3 operators |
| T3 federation | signed handshake (cross-org) | static peers.json | IrohEndpoint or TlsTcpEndpoint | partner-with-partner agents |
| T4 open p2p | verify everything (strangers) | Kademlia DHT + ensemble gossip | IrohEndpoint + relay | autonomous agents finding each other on the open mesh |
Daemon code is identical across all four tiers. The tier is which
Transport impl you plug in. The transport column lists what the
crate implements; the daemon ships T1 and T3 over TCP and over
iroh through the n0 relay mesh, and does not wire TLS. See not
here yet.
Quick tour
Every Rust block below is compiled by cargo test -p ensemble, and
the ones that can run do. The README is included as doctests, so an
example that stops being true stops the build.
Spinning up a humd
use ensemble::{Ensemble, HumdKey};
let key = HumdKey::generate();let me = key.hid();let ensemble = Ensemble::new(me);Adding a peer over the InMemory transport
use ensemble::{Ensemble, HumdKey, InMemoryEndpoint, PeerCapabilities};
#[tokio::main]async fn main() { let me_key = HumdKey::generate(); let peer_key = HumdKey::generate(); let me = me_key.hid(); let peer_id = peer_key.hid();
let caps = PeerCapabilities { proto_version: "0.8.0".into(), ..Default::default() };
let (mine, theirs) = InMemoryEndpoint::pair(me, caps.clone(), peer_id, caps.clone()); let here = Ensemble::new(me); let there = Ensemble::new(peer_id); here.install(mine, caps.clone(), &me_key); there.install(theirs, caps, &peer_key);}Adding a peer over real TCP
use ensemble::{Hid, HumdAddr, TcpTransport, Transport};
# async fn run() -> anyhow::Result<()> {let peer_id = Hid::random_humd();let transport = TcpTransport::new();let addr = HumdAddr::new(peer_id).with_hint("tcp:203.0.113.4:14730");let conn = transport.connect(&addr).await?;# Ok(())# }Adding a peer over Iroh
use ensemble::{Hid, HumdAddr, IrohTransport, Transport};
# async fn run() -> anyhow::Result<()> {let peer_id = Hid::random_humd();let transport = IrohTransport::bind_relayed().await?;let addr = HumdAddr::new(peer_id) .with_hint("iroh:0fb1c87a4d5e4e3a9c1b2d3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f60718") .with_hint("iroh-ip:203.0.113.4:18820") .with_hint("iroh-relay:https://euc1-1.relay.n0.iroh-canary.iroh.link./");let conn = transport.connect(&addr).await?;# Ok(())# }Only the iroh: hint is needed. With it alone the dialer looks up
the peer’s current home relay by its node id and meets it there, then
hole-punches to a direct path when the NATs allow it. iroh-ip: and
iroh-relay: are shortcuts that skip the lookup. tests/iroh_relay.rs
proves both ways across the live n0 mesh with no reachable IP; it is
#[ignore]d so CI never depends on n0.
Sending a tone to one peer
use ensemble::{Ensemble, Hid};use serde_json::json;
# async fn run(ensemble: &Ensemble, me: Hid, peer_id: Hid) -> anyhow::Result<()> {ensemble.route(json!({ "chi": "prompt", "rid": "p1", "sid": "hum-X", "to": peer_id.to_hex(), "from": me.to_hex(), "content": "Hello, peer."})).await?;# Ok(())# }Listening for inbound tones
use ensemble::Ensemble;
# async fn run(ensemble: &Ensemble) {let mut inbox = ensemble.subscribe();while let Ok(tone) = inbox.recv().await { match tone.get("chi").and_then(|v| v.as_str()) { Some("prompt") => println!("prompt: {tone}"), Some("kad-find-node") => continue, _ => continue, }}# }Gossip pub-sub
use ensemble::Ensemble;use serde_json::json;
# async fn run(ensemble: &Ensemble) {let mut sub = ensemble.subscribe_topic("orders/eur-usd");
ensemble.publish( "orders/eur-usd", json!({ "side": "bid", "px": "1.0853", "qty": "10000" }),).await;
while let Ok(payload) = sub.recv().await { println!("quote: {payload}");}# }Finding a humd by id (Kademlia)
use ensemble::{Ensemble, Hid};use std::time::Duration;
# async fn run(ensemble: &Ensemble) {let target = Hid::from_hex( "0fb1c87a4d5e4e3a9c1b2d3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f60718",).expect("a humd id is 32 bytes of hex");
match ensemble.kad_find(target, Duration::from_secs(2)).await { Some(addr) => println!("found {addr:?}"), None => println!("not found among known peers"),}# }What the daemon wires up
The crate is bigger than the daemon. Today, humd:
- speaks TCP (
humd.tcpListen) and iroh over a direct path (humd.irohPort, default41641); - prefers iroh when dialing, and falls back to TCP only for peers iroh could not reach;
- discovers peers from
peers.jsonplus the liveness supervisor’s redial, and keeps one link per peer; - rejects unsigned hellos:
Ensemble::newis strict by default, andwith_strict_auth(me, false)is the opt-out; - publishes its own hive manifests on the
hum/hives/announcetopic, and re-advertises them when a peer joins, so a peer that arrives late still learns what the mesh offers; - routes unicast tones and relays gossip between the peers it holds.
Not here yet
These are written as if they work. They do not.
- A bee cannot publish to the mesh. The daemon’s sink handles
hello,prompt,cancel,attach,peer-add,peer-remove,wane-syncand the rest, but there is nogossip-publisharm, so a tone a bee writes to the local thrum socket never reaches a peer. The daemon publishes bee manifests; a bee’s own topics do not travel. - There is no retraction.
chi:"bee-retract"does not exist, and the ensemble’sbee_retractis called by nothing but a test. A manifest that is announced stays announced. - The DHT cannot bootstrap. The Kademlia table is seeded from
peers.jsonand from the persisted routing store. There is no DNS seeding, no bootstrap node, no contact exchange, sokad_findcan only find peers the node already knows. - TLS is a library capability the daemon never uses.
TlsTcpEndpointand its pinned-fingerprint verifier are here and tested;humdwires only TCP and iroh. - The transport that survives is not the preferred one. One link per peer means the last link admitted wins, and the two sides pick independently. With both TCP and iroh configured, the mesh can end up on the plaintext link even though the iroh dial won the race.
Scenario: phone-laptop roam (T1)
You start a conversation on your laptop, walk to the next room, and continue it on your phone: same hum, no copy-paste, no cloud.
laptop humd phone humd │ (peers.json: each lists the other's LAN address) │ │ TCP or Iroh ├──────────────────► ● ● hum-X hosted here nestler attaches: send chi:"prompt", sid:"hum-X", to: laptop ← chi:"unfurl" / "wilt" routed backIdentity is a key in $XDG_STATE_HOME/hum/humd.key on each device.
Peers list each other in $XDG_CONFIG_HOME/hum/peers.json. Done.
Scenario: federation (T2/T3)
Two organizations want their agents to talk. Each side’s humd has its
own Ed25519 identity; they exchange fingerprints out-of-band (slack
DM, signal, scrap of paper) and pin them in peers.json. From that
point forward, signed chi:"hello" handshakes admit each side to the
other’s ensemble. Unsigned or tampered hellos are rejected, because the
ensemble is strict by default.
Scenario: agents on the open internet (T4)
This is the case worth building toward, and it is the one that is least built. An autonomous agent wants to find other agents offering a service without knowing their addresses and without pre-shared keys. Three pieces have to exist for that, and two of them do not:
-
Onboard: install hum, and the daemon mints an Ed25519 identity at
$XDG_STATE_HOME/hum/humd.key, writes asystemd --userunit, and starts.Terminal window git clone https://github.com/adiled/hum.gitcd hum && ./installsystemctl --user start humdNo binary distribution yet. The only real surfaces are this repo (
github.com/adiled/hum) and the docs site at adiled.github.io/hum. Anything else (ahum.sh, a curl-pipe-sh URL, a package manager entry) does not exist. -
Get advertised: when a bee completes its handshake with a humd that has its hive installed, the daemon builds a
BeeManifestand gossips it on thehum/hives/announcetopic. Every humd subscribed to that topic learns “a bee of market-maker landed on humd X (version, propensity, chi)”. A humd routes to it only if it has the market-maker hive installed too. The mere act of completing a handshake adds you to the on-mesh registry. There is no retraction, and no heartbeat that evicts a manifest whose bee has gone away. -
Get discovered: a peer that wants a service subscribes to the announce topic, and for each manifest it does not recognise asks the DHT where that humd lives:
use ensemble::{Ensemble, Hid};use std::time::Duration;# async fn run(ensemble: &Ensemble) {let mut seen = ensemble.bee_discover("market-maker");while let Some((humd_id, manifest)) = seen.recv().await {if manifest.proto_version != thrum_core::THRUM_VERSION {continue;}let addr = ensemble.kad_find(humd_id, Duration::from_secs(2)).await;println!("{humd_id:?} at {addr:?}");}# }For the broader stream (advertise and retract envelopes) use
ensemble.hive_announcements(). -
Trade: this is the part that does not work yet. A bee that wants to publish its own quotes to the mesh cannot: the daemon publishes hive manifests and nothing else, and there is no
gossip-publisharm in the sink. Unicast works: a tone withto:set is routed to the peer that owns that humd, so request/response between two known peers is fine today. What is missing is a bee putting a topic on the mesh and its counterparties subscribing to it.
Trust scales with what each side reads from the other’s hello:
a signed handshake proves the counterparty owns the Hid it claims,
and nothing more. Whether that counterparty is worth a trade is the
bee’s call. Settlement, payment, rate limits, and reputation all
live above the mesh. ensemble carries tones; it does not interpret
them.
What ensemble does NOT do
These belong to other layers. Keeping them out of ensemble is what keeps the mesh layer thin and reusable.
- Money / payment. No USDC, no x402, no Arc. The settlement bee owns this. ensemble just carries the messages.
- Smart contracts. A bee can post a transaction; ensemble never reads or writes chain state.
- AML / KYC / reputation. A bee layered on top can rate-limit, scorecard, or refuse to fill. ensemble has no policy.
- Model inference. The hives spawn the
nurse that answers a
chi:"prompt". ensemble doesn’t know what is inside the prompt. - Persistence. ensemble is in-RAM. The daemon keeps its own
state under
$XDG_STATE_HOME/hum; peer addresses live inpeers.json. - Routing semantics. A bee that wants to gossip “this hum moved” is responsible for emitting the right topic. ensemble fans the message; it doesn’t interpret.
The protocol surface
When a new bee wants to ride the mesh, it picks which chi values it speaks. The surface today, THRUM_VERSION 0.8.0:
| chi | direction | use |
|---|---|---|
hello | both | Ed25519-signed handshake. Identity proof. |
prompt / unfurl / wilt | both | Inference round-trip routed across humds. |
gossip-publish | both | Mesh-wide pub-sub. Topic + payload + dedup msg_id. |
kad-find-node / kad-find-node-resp | both | DHT lookups for Hids. |
peer-add / peer-remove | both | A peer joined or left. The receiver re-advertises its manifests to a newcomer. |
wane-sync | both | Lamport-clock reconciliation after partition. |
attach / detach | both | Observer joins an existing hum. Handled by the daemon, not the mesh. |
A bee that doesn’t need any of this can ignore most of them.
Boundaries
ensemble is the connectivity primitive. It does not promise:
- That a tone you
routewill be delivered (the peer might be down; try again orkad_findfirst). - That gossip reaches every node within a deadline (best-effort fan-out).
- That a
hellosignature alone makes a peer trustworthy (you decide). - That two humds with the same
Hidare actually one humd (sigs catch that; missing sigs do not). - That a Kademlia response can’t be lied about (handshake on connect catches it; routing-table hints are advisory).
What it promises:
- The same
Transporttrait for every transport in the crate, so daemon code never changes when you swap wires. - Bounded memory (LRU seen-set, K-bucket caps, broadcast back-pressure).
- Honest semantics: every chi value is in
thrum-core::Chi, noextsmuggling, no hidden side channels.
When you build on top, ensemble keeps its hands off your policy. Your bee decides who to trust, what to forward, what to settle.
Try it
cargo test -p ensemblecargo test -p ensemble --test gossip_integrationcargo test -p ensemble --test hives_integrationcargo test -p ensemble --test iroh_integrationcargo test -p ensemble --test kad_integrationcargo test -p ensemble --test tcp_integrationcargo test -p ensemble --test tls_integrationcargo test -p simThe README’s own examples are part of that run: ensemble/tests/readme.rs
includes this file as doctests, so a snippet that stops compiling
fails the build.