A kolo is a circle dance: equal people, hands joined, nobody in the middle. Kolo works the same way. Each peer has its own key, finds the others by topic, connects to them directly and keeps a signed log that anyone can check. No server sits in the path of your data.
Kolo is made by Ciranda.
New here? Start with the tutorial Build a chat in your terminal: two peers on your computer, step by step, in about ten minutes.
What is in the stack
A set of small libraries, each with one job. You can use one of them on its own, or put them together.
Data
- kolo-idPeer identity. Ed25519 keys and short IDs, a 24-word recovery phrase and device certificates.
- kolo-codecCompact binary encoding for messages.
- kolo-logSigned append-only log with Merkle proofs, after RFC 9162.
- kolo-storeLocal storage for logs and keys, on Pebble.
- kolo-blobsEncrypted, content-addressed file storage, read in any range.
- kolo-filesEncrypted folders, names and versions on top of kolo-blobs.
- kolo-syncCopies a log from one peer to another. Pull only.
- kolo-kvA key-value store on a log, with one writer.
- kolo-braidThe signed logs of several members merged into one deterministic order.
Network
- kolo-transportConnections between peers, direct when possible.
- kolo-secureTLS 1.3 channel tied to the peer key.
- kolo-dhtFind peers by topic, with no server.
- kolo-swarmJoin a topic and get connected peers.
- kolo-relayAn optional relay for peers with no direct path.
- kolo-inviteInvite codes for a group or a new device: create one, join with it, approve or deny.
- kolo-moqPublish, subscribe to and relay live tracks, with MoQ Transport draft 22.
- kolo-mediaA catalog, a clock, playout and A/V sync for audio and video frames over kolo-moq.
- kolo-audioAudio devices, playback, resampling, mixing and Opus, with no cgo.
- kolo-videoCamera capture, I420 frames, VP8 and VP9, and optional H.264 from the operating system.
Servers you run
How the pieces fit
How the libraries fit
Each library has one job. The steps follow a peer from its key to its data on other peers.
- kolo-id gives each peer an Ed25519 key. The public key is the peer's identity.
- kolo-dht and kolo-swarm find the peers on a topic and connect to them. kolo-invite lets a new peer join a group with a code.
- kolo-transport carries QUIC connections and kolo-secure ties each one to the peer's key. kolo-relay forwards encrypted packets between two peers with no direct path, only when your app asks it to.
- kolo-log keeps a signed, append-only log, kolo-codec encodes its bytes and kolo-store keeps it on disk. kolo-blobs keeps encrypted files as entries of a log, and kolo-files adds names, folders and versions on top.
- kolo-sync copies a log from one peer to another, kolo-kv reads a log as a key-value store, and kolo-braid merges the logs of several members into one order.
- Two servers you can run: kolo-node, the bootstrap node new peers join through, and kolo-pin, a pinning peer that keeps logs online as ciphertext.
- Live data: kolo-moq publishes tracks and subscribes to them over those connections, and a relay shares one subscription among many subscribers. kolo-media adds a catalog, a clock and playout for encoded audio and video frames. kolo-audio records, plays and resamples audio and encodes it with Opus. kolo-video captures the camera and encodes and decodes video.
- kolo-id gives a peer its Ed25519 key.
- kolo-dht and kolo-swarm find the peers on a topic and connect to them, over kolo-transport and kolo-secure.
- kolo-log keeps a signed, append-only log, and kolo-store keeps it on disk.
- kolo-sync copies a log from one peer to another, and kolo-kv reads a log as a key-value store.
- kolo-node runs the bootstrap server that new peers join through, and kolo-relay helps two peers that cannot reach each other, only if you turn it on.
- kolo-pin runs a pinning peer that keeps your logs available while your devices are offline, as ciphertext it cannot read.
- kolo-moq publishes and subscribes to live tracks over those connections, and a relay shares one subscription among many subscribers. kolo-media adds a catalog, a clock and playout for encoded audio and video frames. kolo-audio lists audio devices, records and plays, resamples, and encodes audio with Opus. kolo-video lists and opens cameras and encodes and decodes VP8 and VP9.
Where to start
- Build a chat in your terminal is the main tutorial: every command, and what you should see after each one.
- Get started runs two peers on one machine and lets them chat.
- Run a pinning peer on a VPS puts a pinning peer on a Linux server and pins a log to it.
- Run your own infrastructure has the commands for your own entry nodes, relay and pin.
- The FAQ answers common questions, each with a link to the page that shows it.
- Concepts explains peers, topics, logs, replicas, deletion and the relay in a page each.
- Limits and Security list what Kolo does not do yet, in plain words.
- For the ideas without code, read How it works and Use cases on kolo.ciranda.dev.
Status
Version 0.1, experimental. The API may change before v1.0.0. Kolo uses IPv4 only. Every page here describes code that exists today; when something is missing, the page says so.