kolo docsbeta

FAQ

Short answers to common questions about Kolo, with a link to the page that shows each one. What is not built yet is on the Roadmap.

On this page

These answers say what is true in Kolo today, each with a link to the page that shows it. What is not built yet is on the Roadmap.

Is Kolo in production?

Not yet. All of Kolo is a beta (0.1): the libraries and the example apps are being tested, and the API can still change before 1.0.0. The Roadmap lists what is not built and what a 1.0.0 needs.

Is Kolo open source?

Yes. Every Kolo library is under the MIT or Apache-2.0 license, at your option, in its own repository. The desktop examples (Kolo Chat, Kolo Share, Kolo Meet and Kolo Board) and their starters are under the Apache-2.0 license only. See Open source on kolo.ciranda.dev.

Does Kolo work without a server?

Peers connect directly to each other, and no server of ours is in the path of your data. To find each other over the internet, the examples use entry nodes (bootstrap), which carry no application data. By default they use the two public entry nodes that Ciranda runs, built into the libraries, so nothing needs to be set up. You can use your own entry nodes instead with -bootstrap, or keep everything on one computer with -local in the examples that have it. A relay is optional and only used when two computers cannot connect directly. Kolo Chat can also use a pin, which keeps an encrypted copy of the messages for people who are offline. A pin is optional: without one, messages reach people only while they are online. Kolo Share, Kolo Meet and Kolo Board use none. See Run your own infrastructure and Built with Kolo.

Do I need to run a server to use Kolo?

No. The libraries and the examples join the public network by default, through two public entry nodes that Ciranda runs, free, with no uptime guarantee while Kolo is a beta. Two people on different networks find each other with no setup. You only run something yourself if you want your own network (an entry node with kolo-node run -first, used with -bootstrap), or if people behind a strict NAT must connect: that needs a relay, and you run it yourself. See Run your own infrastructure.

Is there a public relay or a public pin?

No. There is no public relay and no public pin, and Kolo never defaults to one. What Ciranda does run is two public entry nodes (bootstrap), which the libraries and the examples use by default, free, with no uptime guarantee while Kolo is a beta. Their addresses are built into the library (kolodht.PublicServers). To use your own entry nodes, pass -bootstrap; in a library, pass your own list to Bootstrap, and an empty list that is not nil is refused, so a private network never joins the public one by mistake. The commands for a relay, a pin and your own entry nodes are in Run your own infrastructure.

What can a relay operator see?

The two peers run their own encrypted connection through the relay, so the relay copies bytes it cannot read. In the words of kolo-relay's README:

What the relay learns: both keys of every session, both clients' addresses, which keys hold reservations, when sessions start and end, and the sizes and timing of the inner packets. It cannot read or change them, and it can always drop, delay or end them.

See kolo-relay and Relay.

Can a pin read my messages?

No. A pin holds ciphertext without the keys: it stores and serves signed records, ciphertexts and delete markers, and never gets the entry keys. It still sees which owner keys and log IDs it hosts, their sizes, when they grow, and the key, address and timing of every request. See kolo-pin.

Why does Kolo use IPv4 only?

On purpose: the libraries use IPv4 only, and IPv6 input in any form, IPv4-mapped included, is refused. IPv6 support is a Future item on the Roadmap, with no plan or date. See kolo-node and kolo-swarm for where addresses are checked.

Does removing a member take away their access?

No. In Kolo Chat, an admin can take a member off the member list, and the other copies stop talking to it once they learn of the removal. The removed member keeps the conversation key, so it can still read new messages from the pins, until the chat has a key rotation, which it does not have today (it is Exploring on the Roadmap). See Step 7: Agree on members and rooms with kolo-braid and the derived keys of kolo-log.

Can I use one account on several devices?

Not in the examples yet. Kolo has no accounts: an identity is a kolo-id key, and in the examples one kolo-id lives on one device. The libraries have the parts: kolo-id has a 24-word recovery phrase and device certificates signed by the person's key, kolo-invite links a new device by invite, and the devices package of kolo-braid keeps the devices of a person in a group. No example uses them yet; that is Exploring on the Roadmap. Never copy an example's data folder to a second device.

Why does the example chat not put messages in the braid?

Messages need no agreed order: each member writes its own log, and two messages written at the same moment can be shown in either order. The member list and the room list are shared state that every member must end with in the same form, so only those go into a braid. See Step 7: Agree on members and rooms with kolo-braid.

Does Kolo work on phones or over Bluetooth?

Not yet. Mobile examples and a Bluetooth LE library are on the Roadmap as Exploring and not started. Today the examples run on macOS, Windows and Linux.

Is there a documentation MCP server?

Not yet: it is on the Roadmap as Exploring. Today every page of these docs has a Markdown version in English, Spanish and Portuguese, and the site publishes llms.txt and llms-full.txt for each language, such as /llms.txt.

How do I try it on two computers?

Start each example with no flags: both join the public network, so two computers on different networks find each other. For your own network, run an entry node on a computer both reach and start each example with -bootstrap pointing at it; to stay on one computer, use -local. Add a relay with -relay when the two computers cannot connect directly. The commands are in Run your own infrastructure, and each example's README has a Try it section with one command per block for two computers: the repositories are linked from Built with Kolo.