kolo docsbeta

Paso 1: Construye un chat en tu terminal

Un tutorial paso a paso. Dos peers en tu ordenador se encuentran a través de un nodo de bootstrap y chatean directamente, sin ningún servidor en medio.

En esta página

Este es el primer paso: construyes un chat que funciona en tu terminal.

En unos diez minutos vas a ejecutar tres programas en tu propio ordenador: un nodo de bootstrap y dos copias de un pequeño chat. Los dos chats se encuentran, se conectan directamente y se envían lo que escribes.

Todo se queda en tu ordenador, en la dirección 127.0.0.1. No necesitas ninguna cuenta ni ningún servidor nuestro. Cuando funcione, la última sección lleva el mismo chat a dos ordenadores en redes distintas.

1Comprueba lo que necesitas

Necesitas Go 1.26 o posterior y tres ventanas de terminal. Si aún no tienes Go instalado, instálalo para tu sistema:

Descarga el instalador de macOS (el archivo .pkg) desde go.dev/dl y ejecútalo. Si usas Homebrew, también puedes hacerlo así:

bash
brew install go

Comprueba tu versión de Go:

Terminal
go version

Deberías ver la versión 1.26 o una posterior, por ejemplo:

Texto
go version go1.27.3 darwin/arm64

Abre ahora tres ventanas de terminal y ponlas una al lado de otra:

Abre la app Terminal y pulsa Cmd+N dos veces para tener dos ventanas más.

En este tutorial se llaman Terminal 1 (el nodo de bootstrap), Terminal 2 y Terminal 3 (los dos peers del chat).

2Crea una carpeta y un módulo

En el Terminal 2, crea una carpeta para el chat y entra en ella:

bash
mkdir kolo-chat && cd kolo-chat

Después crea un módulo de Go dentro:

Terminal
go mod init example.com/kolo-chat

Go responde:

Texto
go: creating new go.mod: module example.com/kolo-chat

3Descarga las bibliotecas

Sin salir del Terminal 2, añade las tres bibliotecas de Kolo que usa el chat: kolo-swarm para encontrar peers y conectarse a ellos, kolo-id para la clave de cada peer y kolo-relay para el relay que puedes añadir más tarde.

Terminal
go get github.com/ciranda-dev/kolo-swarm@v0.1.0 github.com/ciranda-dev/kolo-id@v0.1.0 github.com/ciranda-dev/kolo-relay@v0.1.0

Go las descarga junto con lo que necesitan y termina con estas líneas:

Texto
go: added github.com/ciranda-dev/kolo-codec v0.1.0
go: added github.com/ciranda-dev/kolo-dht v0.1.0
go: added github.com/ciranda-dev/kolo-id v0.1.0
go: added github.com/ciranda-dev/kolo-relay v0.1.0
go: added github.com/ciranda-dev/kolo-secure v0.1.0
go: added github.com/ciranda-dev/kolo-swarm v0.1.0
go: added github.com/ciranda-dev/kolo-transport v0.1.0
go: added golang.org/x/crypto v0.59.0
go: added golang.org/x/net v0.63.0
go: added golang.org/x/sys v0.50.0
go: added golang.org/x/time v0.16.0

4Escribe el programa

Crea un archivo llamado main.go en la carpeta kolo-chat y pega dentro este programa. Se une a un topic llamado chat, imprime cada línea que le envía otro peer y envía cada línea que escribes a todos los peers con los que está conectado.

main.go
// Command chat joins a Kolo topic through a bootstrap node and sends each line typed to every connected peer.
package main

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

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

const (
	maxLine     = 4096
	sendTimeout = 10 * time.Second
	codeTooLong = 1
)

func main() {
	boot := flag.String("bootstrap", "127.0.0.1:7447", "IP:PORT of the bootstrap node")
	topic := flag.String("topic", "chat", "topic name")
	lookupOnly := flag.Bool("lookup-only", false, "only look up peers on the topic, do not announce (for a network where announcing fails)")
	every := flag.Duration("lookup-every", 15*time.Second, "time between lookups of the topic (finds peers that join later)")
	relayAddr := flag.String("relay", "", "IP:PORT of a kolo-relay to use when a direct connection fails")
	relayKey := flag.String("relay-key", "", "public key of that relay, in hex")
	listen := flag.String("listen", "127.0.0.1:0", "local IP:PORT to listen on; \":0\" listens on every interface")
	flag.Parse()
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()
	log.SetFlags(log.Ltime)
	if err := run(ctx, *listen, *boot, *topic, *lookupOnly, *every, *relayAddr, *relayKey); err != nil && ctx.Err() == nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context, listen, boot, name string, lookupOnly bool, every time.Duration, relayAddr, relayHex string) error {
	var relayKey []byte
	if relayAddr != "" {
		k, err := hex.DecodeString(relayHex)
		if err != nil || len(k) != 32 {
			return fmt.Errorf("-relay-key must be 64 hex characters")
		}
		relayKey = k
	}
	server, err := netip.ParseAddrPort(boot)
	if err != nil {
		return err
	}
	id, err := koloid.Generate() // in memory only, a new identity each run
	if err != nil {
		return err
	}
	s, err := koloswarm.New(ctx, listen, id, &koloswarm.Config{LookupInterval: every})
	if err != nil {
		return err
	}
	defer s.Close()
	log.Printf("me %x", id.PublicKey()[:4])
	var opts *koloswarm.JoinOptions
	if lookupOnly {
		opts = &koloswarm.JoinOptions{Lookup: true}
	}
	if err := s.Bootstrap(ctx, []netip.AddrPort{server}); err != nil {
		return fmt.Errorf("bootstrap: %w", err)
	}
	if err := s.Join(ctx, koloswarm.Topic(sha256.Sum256([]byte("kolo-chat-example/topic/v0"+name))), opts); err != nil {
		return fmt.Errorf("join: %w", err)
	}
	log.Printf("joined %q, type a line and press Enter", name)
	if relayKey != nil {
		go reserve(ctx, s, relayAddr, relayKey, id)
	}
	dialing := map[string]bool{}

	var mu sync.Mutex
	peers := map[string]*koloswarm.Peer{}
	go func() {
		sc := bufio.NewScanner(os.Stdin)
		sc.Buffer(make([]byte, maxLine), maxLine)
		for sc.Scan() {
			mu.Lock()
			if len(peers) == 0 {
				log.Print("no peer connected yet")
			}
			for _, p := range peers {
				go send(ctx, p, sc.Bytes())
			}
			mu.Unlock()
		}
	}()
	for {
		ev, err := s.Next(ctx)
		if err != nil {
			return err
		}
		switch ev.Kind {
		case koloswarm.Connected:
			mu.Lock()
			peers[string(ev.Peer.PublicKey())] = ev.Peer
			mu.Unlock()
			path := "direct"
			if !ev.Peer.Direct() {
				path = "through the relay"
			}
			log.Printf("peer %x connected (%s)", ev.Peer.PublicKey()[:4], path)
			go receive(ctx, ev.Peer)
		case koloswarm.Found:
			log.Printf("found %x at %v, connecting", ev.PublicKey[:4], ev.Addr)
		case koloswarm.Unreachable:
			log.Printf("could not reach %x directly (%v)", ev.PublicKey[:4], ev.Err)
			if relayKey != nil && !dialing[string(ev.PublicKey)] {
				dialing[string(ev.PublicKey)] = true
				go dialRelay(ctx, s, relayAddr, relayKey, id, ev.PublicKey)
			}
		case koloswarm.Lost:
			mu.Lock()
			delete(peers, string(ev.PublicKey))
			mu.Unlock()
			log.Printf("peer %x lost: %v", ev.PublicKey[:4], ev.Err)
		}
	}
}

// send writes line on a new unidirectional stream, one stream per line.
func send(ctx context.Context, p *koloswarm.Peer, line []byte) {
	ctx, cancel := context.WithTimeout(ctx, sendTimeout)
	defer cancel()
	st, err := p.Conn().OpenUniStream(ctx)
	if err == nil {
		st.SetWriteDeadline(time.Now().Add(sendTimeout))
		if _, err = st.Write(line); err == nil {
			err = st.Close()
		}
	}
	if err != nil && ctx.Err() == nil {
		log.Printf("send to %x failed: %v", p.PublicKey()[:4], err)
	}
}

// receive prints each line p sends, one stream at a time, so a peer cannot make it read many at once.
func receive(ctx context.Context, p *koloswarm.Peer) {
	for {
		st, err := p.Conn().AcceptUniStream(ctx)
		if err != nil {
			return
		}
		st.SetReadDeadline(time.Now().Add(sendTimeout))
		b, err := io.ReadAll(io.LimitReader(st, maxLine+1))
		if err != nil || len(b) > maxLine {
			st.CancelRead(codeTooLong)
			continue
		}
		log.Printf("<%x> %s", p.PublicKey()[:4], printable(string(b)))
	}
}

// printable drops control characters, so a peer cannot move the cursor or clear the terminal.
func printable(s string) string {
	return strings.Map(func(r rune) rune {
		if unicode.IsControl(r) || r == unicode.ReplacementChar {
			return -1
		}
		return r
	}, strings.ToValidUTF8(s, ""))
}

// reserve keeps our key reserved on the relay and attaches every peer that reaches us through it.
func reserve(ctx context.Context, s *koloswarm.Swarm, addr string, key []byte, id *koloid.Identity) {
	for ctx.Err() == nil {
		res, err := kolorelay.Reserve(ctx, addr, key, id, nil)
		if err != nil {
			log.Printf("relay reservation failed: %v; retrying in 10s", err)
			select {
			case <-ctx.Done():
			case <-time.After(10 * time.Second):
			}
			continue
		}
		log.Print("reserved on the relay")
		for {
			c, err := res.Accept(ctx)
			if err != nil {
				break
			}
			go func() {
				if err := s.Attach(ctx, c, false); err != nil && ctx.Err() == nil {
					log.Printf("relayed peer %x not attached: %v", c.RemotePublicKey()[:4], err)
				}
			}()
		}
		res.Close()
	}
}

// dialRelay connects to peer through the relay and hands the connection to the swarm.
func dialRelay(ctx context.Context, s *koloswarm.Swarm, addr string, key []byte, id *koloid.Identity, peer []byte) {
	log.Printf("trying %x through the relay", peer[:4])
	c, err := kolorelay.Dial(ctx, addr, key, id, peer, nil)
	if err != nil {
		log.Printf("relay dial to %x failed: %v", peer[:4], err)
		return
	}
	if err := s.Attach(ctx, c, true); err != nil && ctx.Err() == nil {
		log.Printf("relayed peer %x not attached: %v", peer[:4], err)
	}
}

Conviene saber algunas cosas sobre él:

  • Cada ejecución crea una clave nueva en memoria, así que cada peer recibe un nombre nuevo cada vez que lo arrancas. Su nombre son los 4 primeros bytes de su clave pública.
  • Una línea que escribas antes de que haya algún peer conectado muestra no peer connected yet y no se envía.
  • Lee la dirección del nodo de bootstrap del flag -bootstrap, y 127.0.0.1:7447 es el valor por defecto. -listen es la dirección en la que escucha: 127.0.0.1:0 por defecto, que lo deja en tu ordenador; usa :0 para llegar a otros ordenadores.
  • Vuelve a buscar el topic cada 15 segundos (-lookup-every), así que encuentra a los peers que entran más tarde. -lookup-only busca sin anunciarse.
  • -relay y -relay-key indican un servidor de kolo-relay que probar cuando falla una conexión directa. Sin ellos no se usa ningún relay.
  • Lo que envía otro peer no es de confianza: el programa lee como máximo 4.096 bytes por mensaje y quita los caracteres de control antes de imprimirlo.

5Arranca un nodo de bootstrap en el Terminal 1

El nodo de bootstrap es la primera dirección a la que preguntan los peers. Les ayuda a encontrarse y luego se aparta: tus mensajes nunca pasan por él.

En el Terminal 1, instala kolo-node:

Terminal
go install github.com/ciranda-dev/kolo-node/cmd/kolo-node@v0.1.0

Puede que Go imprima algunas líneas go: downloading y luego nada más. El programa va a la carpeta bin de Go. Si en el siguiente paso tu shell no encuentra kolo-node, añade esa carpeta a tu PATH en este terminal:

bash
export PATH="$PATH:$(go env GOPATH)/bin"

Arranca el nodo solo en tu ordenador, con su clave en una carpeta temporal nueva:

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

-first arranca una red nueva: este nodo no tiene otros nodos de entrada a los que unirse. Imprime tres líneas y sigue en marcha. Tus horas y tu clave serán distintas:

Texto
time=2026-11-11T18:51:56.880+07:00 level=INFO msg=identity key=152978a8aa6e5a00500cdc20c26ec281ba9b3a5f1dd17fd617354488f40a3cda created=true
time=2026-11-11T18:51:56.880+07:00 level=INFO msg=started version=v0.1.0 addr=127.0.0.1:7447
time=2026-11-11T18:51:56.880+07:00 level=INFO msg=network mode=first entries=0

Deja abierto el Terminal 1.

6Arranca el primer peer en el Terminal 2

En el Terminal 2, dentro de la carpeta kolo-chat, ejecuta el chat:

Terminal
go run .

La primera vez tarda un momento en compilar. Después el peer imprime su nombre y espera:

Texto
18:51:59 me 19353b70
18:51:59 joined "chat", type a line and press Enter

7Arranca el segundo peer en el Terminal 3

En el Terminal 3, ve a la misma carpeta kolo-chat (usa la ruta donde la creaste) y vuelve a ejecutar el chat:

Terminal
cd kolo-chat
Terminal
go run .

En pocos segundos los dos peers se encuentran. El Terminal 3 muestra:

Texto
18:52:07 me ffdabb7a
18:52:07 joined "chat", type a line and press Enter
18:52:07 found 19353b70 at 127.0.0.1:52144, connecting
18:52:07 peer 19353b70 connected (direct)

El puerto después de 127.0.0.1 será otro. El Terminal 2 añade una línea con el nombre del peer nuevo, y puede mostrar una línea found para él en su siguiente búsqueda:

Texto
18:52:07 peer ffdabb7a connected (direct)

8Escribe una línea y mira cómo llega

En el Terminal 2, escribe una línea y pulsa Intro:

Texto
hello from terminal 2

Aparece en el Terminal 3, junto al nombre del peer que la envió:

Texto
18:52:23 <19353b70> hello from terminal 2

Ahora responde desde el Terminal 3:

Texto
hi, terminal 3 here

Y el Terminal 2 muestra:

Texto
18:52:31 <ffdabb7a> hi, terminal 3 here

9Páralo todo

Pulsa Ctrl-C en el Terminal 3. Ese peer se detiene, y el Terminal 2 se da cuenta:

Texto
18:52:46 peer ffdabb7a lost: koloswarm: connection lost

Pulsa Ctrl-C en el Terminal 2. Después pulsa Ctrl-C en el Terminal 1; el nodo se despide con estas líneas y termina:

Texto
time=2026-11-11T18:52:54.949+07:00 level=INFO msg=stopping cause="interrupt signal received"
time=2026-11-11T18:52:54.951+07:00 level=INFO msg=stats servers=0 records=2 requests=16 limited=0 closed=0 since=58s
time=2026-11-11T18:52:54.952+07:00 level=INFO msg=stopped

Dos ordenadores en redes distintas

El mismo programa funciona entre dos ordenadores, por ejemplo uno en casa y otro en el trabajo. Los ejemplos de Kolo terminados, y cualquier programa que llame a Bootstrap(ctx, nil) sin lista, usan los nodos de entrada públicos que ejecuta Ciranda, así que no necesitan configuración. Este chat toma su nodo de entrada de -bootstrap, así que aquí ejecutas un nodo de entrada propio: una tercera máquina a la que lleguen los dos ordenadores, un host con una dirección IPv4 pública, como un VPS pequeño. Los pasos usan 203.0.113.10 como su dirección; usa la tuya.

En ese host, instala kolo-node como en el paso 5, abre el puerto UDP 7447 en su firewall (y en el del proveedor, si tiene uno) y arranca el nodo en todas sus direcciones:

Terminal
kolo-node run -listen :7447 -identity "$HOME/kolo-node/node.key" -first

Desde cada ordenador, comprueba que el puerto está abierto y arranca el chat escuchando en todas las interfaces:

Terminal
kolo-node check 203.0.113.10:7447
Terminal
go run . -listen :0 -bootstrap 203.0.113.10:7447

Qué significan las líneas:

  • found <peer> at <address>, connecting: la búsqueda ha devuelto el otro peer y el chat está abriendo una conexión con él.
  • peer <peer> connected (direct): los dos ordenadores hablan directamente; el host solo les ayudó a encontrarse.
  • could not reach <peer> directly (...): no hay camino directo. Los dos lados enviaron paquetes para abrir uno (hole punching) y las redes los descartaron.
  • join: ... al arrancar: el chat no pudo anunciar ni buscar el topic. Si lo que falla en esa red es el anuncio, prueba -lookup-only allí: ese chat sigue encontrando al otro, pero no se le puede encontrar, así que arráncalo el segundo.

Una red corporativa o una VPN pueden bloquear el anuncio, el hole punching o ambos. Entonces necesitas un relay.

Un relay para cuando no hay camino directo

Esta parte se ha probado entre dos ordenadores por internet, a través de un relay en un host en la nube.

kolo-relay reenvía paquetes cifrados entre dos peers que no pueden llegar el uno al otro. No puede leerlos: dentro va la propia conexión kolo-secure de los peers. En el mismo host público, crea una segunda carpeta y un módulo para el servidor del relay:

bash
mkdir kolo-relay-server && cd kolo-relay-server && go mod init kolo-relay-server
Terminal
go get github.com/ciranda-dev/kolo-id@v0.1.0 github.com/ciranda-dev/kolo-relay@v0.1.0

Guarda esto como main.go. Guarda su clave en relay.key (o en el archivo que pases con -identity), así que la clave no cambia entre reinicios:

main.go
// Command relay runs a kolo-relay server for the chat example.
package main

import (
	"context"
	"errors"
	"flag"
	"io/fs"
	"log"
	"os"
	"os/signal"

	koloid "github.com/ciranda-dev/kolo-id"
	kolorelay "github.com/ciranda-dev/kolo-relay"
)

func main() {
	listen := flag.String("listen", ":7448", "UDP IP:PORT to listen on")
	keyFile := flag.String("identity", "relay.key", "identity file, created if missing")
	flag.Parse()
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()
	log.SetFlags(log.Ltime)

	id, err := koloid.Load(*keyFile)
	if errors.Is(err, fs.ErrNotExist) {
		if id, err = koloid.Generate(); err == nil {
			err = id.SaveNew(*keyFile)
		}
	}
	if err != nil {
		log.Fatal(err)
	}
	s, err := kolorelay.Listen(ctx, *listen, id, nil)
	if err != nil {
		log.Fatal(err)
	}
	defer s.Close()
	log.Printf("relay on %v, key %x", s.Addr(), id.PublicKey())
	<-ctx.Done()
}

Abre el puerto UDP 7448 en el host y arráncalo:

Terminal
go run . -listen :7448

Muestra una línea, relay on <address>, key <key>, donde la clave son 64 caracteres hexadecimales. Arranca los dos chats con la dirección del relay y esa clave completa:

Terminal
go run . -listen :0 -bootstrap 203.0.113.10:7447 -relay 203.0.113.10:7448 -relay-key <relay key>

Cada chat muestra reserved on the relay. Cuando falla una conexión directa, el chat muestra trying <peer> through the relay, y luego el peer se conecta a través del relay y las líneas van en los dos sentidos. De esa prueba:

Texto
14:52:42 reserved on the relay
14:54:37 peer 8b4cc656 connected (through the relay)
14:54:50 <8b4cc656> hello

El relay solo se usa porque pasaste -relay; nada recurre a él por su cuenta.

Qué acaba de pasar

  • Cada peer se unió al topic chat a través de la DHT del nodo de bootstrap: se anunció allí y buscó el topic. Así es como el segundo peer encontró al primero. Consulta Topics.
  • Cuando se encontraron, los dos peers se conectaron directamente. El nodo de bootstrap solo les ayudó a conocerse; tus mensajes nunca pasaron por él.
  • La conexión es un canal cifrado ligado a la clave de cada peer, gracias a kolo-secure. Cada lado conoce la clave completa del peer con el que habla. Consulta Peers.
  • En los primeros pasos todo se ejecutó en 127.0.0.1, así que solo podían unirse programas de tu ordenador. Entre ordenadores, tu propio nodo de bootstrap se ejecuta en un host al que llegan los dos y cada chat escucha en :0; la página de kolo-node explica cómo ejecutar el nodo de verdad.

Siguientes pasos

  • Lee la página de kolo-swarm: su API, sus límites y qué significa cada evento.
  • Lee los Conceptos: peers, topics, logs, réplicas, borrado y el relay, con una página corta para cada uno.
  • Mira qué más puedes construir en kolo.ciranda.dev: Casos de uso.