Knolo Exchange Relays: Store-and-Forward Without Trusting the Middle
A Knolo Exchange relay holds signed offers and Knowledge Image bytes so the sender can go offline. The recipient, not the relay, still verifies everything.
Knolo is the open-source, local-first Knowledge Image runtime and format: Apache-2.0, with @knolo/core on npm and the source in the Knolo core repo on GitHub. Knolo Exchange is how one agent hands a complete Knowledge Image to one named recipient. On 16 Nov 2026 a store-and-forward relay for those offers merged to main in PR #193. This note looks at the design choice behind it: the relay holds bytes, and the recipient still decides what to trust.
Why Knolo Exchange needed a relay
KIP-0028 defines a signed offer, an accept or reject decision, and a receipt for one V5 Knowledge Image. The KIP draws a boundary on purpose: sockets, TLS, peer URLs, policy files and cache paths belong to the host package, not to the contract. Core does not read a clock, a socket or the filesystem.
Before #193, the sender's host had to stay online. knolo exchange serve registered the offer locally and the recipient pulled from it. The alternative was a file handoff with export and import. A relay fills the gap between those two: the sender uploads and can go offline, and the recipient pulls later.
What a Knolo Exchange relay does
knolo exchange relay --config relay.json stores offer CBOR and image blobs by digest. A sender uploads with offer --via <https-url>, and a recipient pulls with pull --from set to that relay's https:// URL. The routes are small:
PUT /v1/blobs/:sha256, thenPOST /v1/offersto uploadGET /v1/offers/:idto read an offerPOST /v1/offers/:id/decisionfor the recipient's decisionGET /v1/blobs/:sha256to download the image
relay.json sets the listen address, TLS certificate and key, a store directory, maxBytes, retentionMs, and a senders list of offer keyId values allowed to upload. After an offer's expiresAt plus the retention period, a sweep removes the offer and any blob no remaining offer names.
What a Knolo Exchange relay does not check
The relay checks shape, not trust. It confirms the offer CBOR is well formed, the keyId is on the senders list, the offer has not expired, and the stored blob's length and SHA-256 match the offer. It does not verify the offer or the decision for the recipient. It does not mount, adopt or rewrite bytes.
The README is direct about the limits. The senders list is a name filter, not a signature check, so anyone who can reach the relay and name an allowed keyId can fill its store. A changed blob is served as stored.
That is acceptable because verification never moved. The recipient's host still checks the signature, the recipient, the expiry, the receive policy, the SHA-256 and the stateRoot, and refuses a blob that does not match. Shipped exchange configs keep adopt at deny. A relay can lose or delay an image. It cannot make a recipient accept the wrong one.
Where the Knolo relay sits in the open technology
The relay adds no new KIP. KIP-0028 already says transport belongs to the host, and #193 is a host feature in @knolo/exchange. The package version stays 0.1.0, the published npm version, so the relay is on main but not yet in a release. Two more boundaries from the README:
- Knolo Hub is not this relay, and there is no hosted relay. You run it yourself.
- Pull and import do not adopt the image into a store, write
knolo.lock.json, or call Hub.
Exchange conformance cases live in conformance/exchange/v1. For how Knolo specifications are published and versioned, see specifications, lifecycle, compatibility and the Knolo KIP index.
Read more about Knolo
Start at Knolo open technology on knolo.org. For commands and package versions, use the Knolo docs on knolo.dev.
knolo · exchange · open-technology · kip-0028 · open-source
