kolo docsbeta

Get started

Run a bootstrap node and two chat peers on one machine. The peers find each other by topic and talk directly.

On this page

You will run three programs on one machine, all on 127.0.0.1:

  1. a kolo-node bootstrap server, the address new peers join through;
  2. two copies of a small chat program built on kolo-swarm.

The two chat peers join the same topic, find each other through the node, connect directly and send each other the lines you type. The node only helps them meet; your messages never go through it.

You need Go 1.26 or newer.

This walk-through keeps everything on your computer, with an entry node of your own on loopback. A library with no list of entry nodes joins the public network instead, through the two public entry nodes that Ciranda runs, built into kolo-dht.

Run a bootstrap node

Install kolo-node:

go install github.com/ciranda-dev/kolo-node/cmd/kolo-node@latest

In a first terminal, start it on loopback, with its key in a new temporary directory:

Terminal
dir=$(mktemp -d)
kolo-node run -listen 127.0.0.1:7447 -identity "$dir/node.key" -first

-first starts a new network: this node has no other entry nodes to join. Leave it running. From another terminal, kolo-node check 127.0.0.1:7447 prints ok 127.0.0.1:7447.

Write the chat program

Make a new module and add the two libraries it uses:

Terminal
mkdir chat && cd chat
go mod init chat
go get github.com/ciranda-dev/kolo-id github.com/ciranda-dev/kolo-swarm

Save this as main.go:

main.go
// Command chat joins a topic and sends each line you type to every peer on it.
package main

import (
	"bufio"
	"context"
	"crypto/sha256"
	"flag"
	"fmt"
	"io"
	"log"
	"net/netip"
	"os"
	"strings"
	"sync"
	"unicode"

	koloid "github.com/ciranda-dev/kolo-id"
	koloswarm "github.com/ciranda-dev/kolo-swarm"
)

func main() {
	flag.Parse()
	if flag.NArg() == 0 {
		log.Fatal("usage: chat IP:PORT...")
	}
	var servers []netip.AddrPort
	for _, a := range flag.Args() {
		ap, err := netip.ParseAddrPort(a)
		if err != nil {
			log.Fatal(err)
		}
		servers = append(servers, ap)
	}
	ctx := context.Background()

	id, err := koloid.Generate()
	if err != nil {
		log.Fatal(err)
	}
	s, err := koloswarm.New(ctx, "127.0.0.1:0", id, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer s.Close()
	if err := s.Bootstrap(ctx, servers); err != nil {
		log.Fatal(err)
	}
	topic := koloswarm.Topic(sha256.Sum256([]byte("kolo chat example")))
	if err := s.Join(ctx, topic, nil); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("you are %x; type a line and press Enter\n", id.PublicKey()[:4])

	var mu sync.Mutex
	peers := map[*koloswarm.Peer]bool{}
	go func() {
		for {
			ev, err := s.Next(ctx)
			if err != nil {
				return
			}
			switch ev.Kind {
			case koloswarm.Connected:
				mu.Lock()
				peers[ev.Peer] = true
				mu.Unlock()
				fmt.Printf("* %x joined\n", ev.Peer.PublicKey()[:4])
				go receive(ctx, ev.Peer)
			case koloswarm.Lost:
				mu.Lock()
				delete(peers, ev.Peer)
				mu.Unlock()
				fmt.Printf("* %x left\n", ev.Peer.PublicKey()[:4])
			}
		}
	}()

	lines := bufio.NewScanner(os.Stdin)
	for lines.Scan() {
		mu.Lock()
		for p := range peers {
			go send(ctx, p, lines.Text())
		}
		mu.Unlock()
	}
}

// send opens a one-way stream per message; closing it marks the end.
func send(ctx context.Context, p *koloswarm.Peer, msg string) {
	st, err := p.Conn().OpenUniStream(ctx)
	if err != nil {
		return
	}
	st.Write([]byte(msg))
	st.Close()
}

func receive(ctx context.Context, p *koloswarm.Peer) {
	for {
		st, err := p.Conn().AcceptUniStream(ctx)
		if err != nil {
			return
		}
		msg, _ := io.ReadAll(io.LimitReader(st, 4096))
		// The text comes from another machine: drop control characters
		// before printing it to a terminal.
		clean := strings.Map(func(r rune) rune {
			if unicode.IsControl(r) {
				return -1
			}
			return r
		}, string(msg))
		fmt.Printf("%x: %s\n", p.PublicKey()[:4], clean)
	}
}

Run two peers

In a second terminal:

Terminal
go run . 127.0.0.1:7447

In a third terminal, run the same command again. After a moment each peer prints * <key> joined with the first bytes of the other's public key. Type a line in one terminal and press Enter: it shows up in the other one, next to the sender's key. Stop a peer with Ctrl-C and the other prints * <key> left.

What just happened

  • Each peer made a new kolo-id key. Its public key is its name on the network. See Peers.
  • Both joined the topic sha256("kolo chat example"). Joining with nil options announces the peer on the topic and looks the topic up. See Topics.
  • The second peer found the first through the node's kolo-dht server and dialed it. The connection is a kolo-secure channel tied to each peer's key, so each side knows whose key it is talking to.
  • Each message travels on its own one-way stream, straight from one peer to the other.

Next steps

  • To keep a history that peers can check, write messages to a kolo-log log and copy it with kolo-sync. See Logs and Replicas.
  • To run peers on different machines, call Bootstrap(ctx, nil) with no list: the peers join the public network through the public entry nodes, free, with no uptime guarantee while Kolo is a beta. For a network of your own, run a few kolo-node servers on hosts with a public IPv4 address and pass their addresses to every peer. The kolo-node page has the details.
  • Two peers that cannot reach each other directly can use a relay, if you choose to run one.