A library page shows one piece at a time. An example shows the pieces working together: how a peer is found, where the messages are kept, who can join.
These are example programs, written by the Kolo team to show the libraries working together. They are demonstrations, not production software and not products, and they are beta, like the libraries. They are not third-party projects. The libraries are under the MIT or Apache-2.0 license, at your option; the examples and their starters are under Apache-2.0 only.
The examples
Desktop chat
WorkingA desktop chat example made with Wails 3. Messages go directly from peer to peer, or through a relay you run when two computers cannot connect directly, and are kept in an encrypted log. An optional pin keeps them for people who are offline, new people join with an invite, and each conversation is a room in one list, with profiles. A room connects again by itself and never gives up. It is the example you build in the tutorial, one step at a time.
Source code
ciranda-dev/kolo-chat-wails3-example
Libraries
Tutorial
File sharing desktop example
WorkingA desktop example made with Wails 3. It sends a file or a folder in a session that two people open with a code, and receives it on the other side, with kolo-blobs and kolo-files. A download that was cut continues by itself, and items of 100 GB work.
Source code
ciranda-dev/kolo-share-wails3-example
Libraries
Tutorial
Shared kanban board
WorkingA desktop kanban board made with Wails 3 that several people edit at the same time, on kolo-braid. Each computer syncs straight with the others, or through a relay you run, members join with an invite, and the board shows which cards are settled.
Source code
ciranda-dev/kolo-board-wails3-example
Libraries
- kolo-id
- kolo-dht
- kolo-swarm
- kolo-secure
- kolo-transport
- kolo-relay
- kolo-codec
- kolo-store
- kolo-sync
- kolo-invite
- kolo-braid
Tutorial
Video meetings desktop example
WorkingA desktop example made with Wails 3 for calls with audio and video. One person creates an invite, and the others join the call with it. The picture follows the network, from 360p up to 1080p, and a call comes back by itself after a dropped connection. The host can remove a participant.
Source code
ciranda-dev/kolo-meet-wails3-example
Libraries
- kolo-id
- kolo-dht
- kolo-swarm
- kolo-secure
- kolo-transport
- kolo-relay
- kolo-store
- kolo-invite
- kolo-moq
- kolo-media
- kolo-audio
- kolo-video
Tutorial
Need a relay or a pin?
Every example needs entry nodes to find the others, and it has three network modes:
- Public network (default). With no flag, the example uses the two public entry nodes that Ciranda runs, built into the libraries. Nothing to set up: two people on different networks find each other. It is free, with no uptime guarantee while Kolo is a beta.
- Your own network.
-bootstrap host:port[,host:port]uses your own entry nodes, alone. - This computer only.
-localkeeps everything on 127.0.0.1. Kolo Share, Kolo Meet and Kolo Board have it; Kolo Chat does not.
There is no public relay and no public pin: both stay optional and you run your own. The commands are in Run your own infrastructure.
Kolo Chat
- Window: one list of rooms in the sidebar, each conversation being one room. The sidebar folds into a narrow rail. The "+" beside the list opens a menu with "Create a room" and "Join a room", each in a dialog of its own. Messages from the same person within five minutes sit together under one name and one time. The window does not show the addresses of the public entry nodes.
- Pin: optional. Without one, messages reach people only while they are online. With one, it keeps an encrypted copy of the messages for people who are offline: every member derives the message keys from the conversation key, so a message is read from a pin even while its sender is offline. The pin needs an address every member reaches: the example never reaches a pin through a relay.
- Rooms: one example keeps 64 rooms by default;
-max-conversationschanges it, from 1 to 256. - Network states: a room shows its state as a dot in the list, under its name and in a note: connecting, online, reconnecting or offline, never as an error. A room never freezes or gives up. When no entry node answers, it still starts, works from its own log and asks again by itself, waiting 2 seconds and doubling up to 30. When the last connection to a peer ends, it says "reconnecting" for up to 45 seconds, dials the peers again, and each side pulls what the other wrote meanwhile. Messages typed meanwhile are kept in the room's log and shown once, in order, when the connection returns. A pin that cannot be reached is tried again with a growing wait.
- Many rooms: the example starts its rooms four at a time, the one on screen first, because a public entry node lets one address send 50 requests a second.
- Relay: optional, for two computers behind strict NATs that cannot connect directly. When the direct connection fails, the invite, the messages and the sync of the history, names and rooms go through it, and it cannot read them.
- Start every example with the same relay:
-relay host:port@key, repeated or as a comma list,-relay-file, orKOLO_CHAT_RELAYSwhen neither flag is given; at most 16. The invite does not carry the relays. Settings shows each relay's state. - Secrets: the conversation key and the pin token are never flags, since
a flag shows in the process list and the shell history.
-conversation-keyand-pin-tokenare refused with a message that names the variable and the file. SetKOLO_CHAT_CONVERSATION_KEYandKOLO_CHAT_PIN_TOKEN, or use-conversation-key-fileand-pin-token-file(alsoKOLO_CHAT_CONVERSATION_KEY_FILEandKOLO_CHAT_PIN_TOKEN_FILE), which read the secret from a file that only its owner can open. - Memory: a soft memory limit is set at start: half of the physical
memory, never below 512 MiB, and 2 GiB when the memory cannot be read.
GOMEMLIMITreplaces it. - Version: Settings shows the release under About, the git tag of the
build; a build without one shows
dev.
Kolo Share
- Window: a sidebar with your sessions, which folds into a narrow rail, a "+" menu with "Show a code" and "Paste a code", and a card with History and Settings. One quiet line says which network the example is on. The other person sees an item as "being prepared" while you prepare it, then the same row becomes the offer. Rows show the real progress and speed, and say so when nothing moved for a while.
- Resume: a download that was cut continues by itself from the chunks it
already verified.
-resume-for(orKOLO_SHARE_RESUME_FOR) sets how long it waits for bytes that stopped; the default is 30 minutes. Items of 64 MiB or more use a store tuned for large data. - Big items: an item of 100 GB works.
-max-download(orKOLO_SHARE_MAX_DOWNLOAD) is a safety bound, 1 TiB by default. The disk is checked before the first byte, in the data folder and in the chosen folder, and a short disk ends the transfer at once and says how much is needed and how much is free. Up to 4 items of a session are received at once. - Speed: the connection to a paired computer paces what it sends with BBR
by default, and
-congestion reno|cubic|bbr(orKOLO_SHARE_CONGESTION) changes it. BBR keeps a standing queue of 25 to 150 ms and takes bandwidth from other flows, so setrenoon a shared link. The receive windows grow only for the paired computer, and every other connection keeps small ones. The pairing connections stay on Reno. - Relay: optional, for two computers behind strict NATs that cannot connect directly. When the direct connection fails, the pairing, the session and its files go through it, and it cannot read them.
- Pin: not used. A session moves files only while both examples are open.
- Start both examples with the same relay:
-relay host:port@key, repeated or as a comma list,-relay-file, orKOLO_SHARE_RELAYSwhen neither flag is given; at most 16. A relay with an allow list never holds a pairing code, so a pairing through it works only when the computer that shows the code is reachable directly. - Connection numbers: the
transfer:lines of the log end with what kolo-transport'sConn.Statsmeasured on the connection: the round trip (rtt,min_rtt), the congestion window and the bytes in flight (cwnd,in_flight), the packets sent and lost and the bytes lost, the controller (cc), BBR's bandwidth estimate (bw_mbs) and the moves to a new path (path_changes). No name, key or address is logged. - Long names: a name or a path that this computer cannot save is refused before the download: 255 bytes for a name on macOS and Linux, and a path of 1023 bytes on macOS, 4095 on Linux and 32767 UTF-16 units on Windows.
- Memory: a soft memory limit is set at start: half of the physical
memory, at least 512 MiB, and 2 GiB when the memory cannot be read.
GOMEMLIMITreplaces it. - Version: Settings shows the git tag of the build; a build without one
shows
dev.
Kolo Meet
- Call relay: the host's example runs it for each call, and every person's media goes through it. Nothing to install.
- Connection relay: optional, for two computers behind strict NATs that
cannot connect directly. It carries the connection to the call's relay
and the key links between participants, and cannot read them. Give it to
every example with
-relay,-relay-fileorKOLO_MEET_RELAYS; at most 16. A guest who cannot reach the host directly needs a relay without an allow list, since the call's relay has a key made for that call. - Quality: the camera goes up and down a ladder of three pictures, 360p,
720p and the ceiling of
-video-size(1080p by default), by itself: down at once when the connection to the call's relay cannot carry the picture, up after a few seconds of a clear path. With several guests the best path decides. - Bad connections: a call tries for up to 60 seconds to get its session to the relay back before it ends, and the relay keeps the guest's place for the same time, so nobody sees the guest leave. A watchdog starts a new session when a person who sends delivers nothing for 6 seconds. A viewer that lost a group asks the sender for a key frame.
- Pin: not used. A call keeps nothing for later.
- The host can remove a participant. The invites that exist at that moment no longer let that person back in; a new invite from the host does.
- Invites: the invite is served by a second network node under a key of its own, and the call's relay only by the people the host let in. A stranger with the invite reaches only the invite node, which keeps kolo-transport's 16 incoming streams; people in the call keep 1000. A host of this version needs guests of this version.
- Drawing:
-display-fps(orKOLO_MEET_DISPLAY_FPS) sets the pictures a second each tile of the window draws:auto(the default: 30 while at most 4 other people show video, 15 with more),30or15. - Connection numbers: the
localline of the call quality report, and of-quality-log, has anetobject with what kolo-transport measured on the connections to the relay: round trip, loss, congestion window, bytes in flight, controller, BBR's bandwidth estimate and path changes. It holds no address or key. - Memory: a soft memory limit of 2 GiB is set at start unless
GOMEMLIMITis set, and the log says which. - Version: the git tag, in Settings, in the status and in every package;
devin a development build.
Kolo Board
- Window: a sidebar with the board, which folds into a narrow rail, how many cards are settled and syncing, one quiet line about the network, and a card with Settings. The header has the board name, the members and the buttons Invite, Activity and Members.
- Relay: optional, for two computers behind strict NATs that cannot connect directly. When the direct connection fails, the invite, the join and the board's sync go through it, and it cannot read what it passes on.
- Settlers: a change settles when enough settlers are online. The example
admits every joiner with
AdmitOptions.GrowSettlers, which decides who settles: with one or two members only the creator, with three all three, with four or more four of them, and later joiners are plain members. The window shows how many are online, and changes stay syncing while there are too few. - Pin: not used. Members sync straight with each other while they are online at the same time.
- Start every example with the same relay:
-relay host:port@key, repeated or as a comma list,-relay-file, orKOLO_BOARD_RELAYSwhen neither flag is given; at most 16. The invite does not carry the relays. Settings shows each relay's state, and a relay listed with a wrong key is reported a few seconds after the start. - Memory: a soft memory limit of 2 GiB is set at start unless
GOMEMLIMITis set, and one log line names the limit. - Version: the git tag of the build; a build without one, and
wails3 dev, saydev.
Try Kolo Board
Kolo Board is a desktop kanban board that several people edit at the same time, on kolo-braid: only columns and cards, no chat, no comments and no attachments. You need Go 1.26 or later, Node.js with npm and the Wails 3 CLI. Run the commands in the repository folder.
Once: build the example.
wails3 buildOnce: make a private folder for the demo data.
mkdir -p -m 700 /tmp/kolo-board-demoWith no flags the example joins the public network. The two commands below keep
the demo on this computer instead, with an entry node of your own on
loopback (-local does the same in one flag). Terminal 1: Ana. -first
makes her example run the entry node on loopback too.
./bin/kolo-board -data /tmp/kolo-board-demo/ana -first 127.0.0.1:4000Terminal 2: Bia.
./bin/kolo-board -data /tmp/kolo-board-demo/bia -bootstrap 127.0.0.1:4000In Ana's window choose a name, create a board and make an invite. In Bia's
window choose a name, paste the invite and join. Keep Ana's window open: it is
the entry node. On two computers, start both examples with no flags to use the
public network, or run a kolo-node entry node of your own and pass
-bootstrap, as in
Run your own infrastructure.
Kolo Playground
Kolo Playground is a private test tool, not a library and not one of the examples. Its
braid-peer runs one kolo-braid member as its own process, and
braid-scenarios starts several of them on 127.0.0.1, each in a temporary
directory, and runs multi-peer scenarios: convergence, partition and heal,
concurrent membership changes, forked writers, spam, kill -9, restored and
copied devices, and joiners. Each scenario ends with the same settled
digests on every honest peer, or with the halt it expects, and prints a
cost report. Run the commands in the repository folder.
List the scenarios:
go run ./cmd/braid-scenarios -listRun one:
go run ./cmd/braid-scenarios -run partition-healRun one peer by hand, as the founder of a new braid in a temporary directory. It reads commands on stdin and prints one JSON object per line:
go run ./cmd/braid-peer --firstTest the harness and every short scenario:
go test ./...What the cards say
- Working: the example runs and you can try it, and we keep updating it. Its card links a tutorial and the page of each library it uses. For Kolo Chat and Kolo Meet the tutorial builds the example. Kolo Share and Kolo Board have no step-by-step guide of their own: their card links the tutorial of their main library (kolo-blobs and kolo-files, or kolo-braid), and the code of the example is in its repository.
- In progress: we are building it. The card has no links yet, and it gets them when the example is done.
Like every Kolo library, these examples are beta: they follow the v0.x libraries and change with them.