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í:
brew install goDescarga el instalador de Windows (el archivo .msi) desde
go.dev/dl y ejecútalo. Añade Go a tu PATH. Después
abre PowerShell.
Usa el paquete golang de tu distribución si es la versión 1.26 o
posterior. Si no, descarga el archivo .tar.gz desde
go.dev/dl y sigue los pasos para Linux de
go.dev/doc/install.
Comprueba tu versión de Go:
go versionDeberías ver la versión 1.26 o una posterior, por ejemplo:
go version go1.27.3 darwin/arm64Abre 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.
Abre PowerShell tres veces, o abre Windows Terminal y pulsa Ctrl+Shift+T dos veces para tener dos pestañas más.
Abre tu app de terminal y pulsa Ctrl+Shift+N dos veces para tener dos ventanas más (en la mayoría de los terminales, Ctrl+Shift+T abre pestañas).
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:
mkdir kolo-chat && cd kolo-chatmkdir kolo-chat; cd kolo-chatmkdir kolo-chat && cd kolo-chatDespués crea un módulo de Go dentro:
go mod init example.com/kolo-chatGo responde:
go: creating new go.mod: module example.com/kolo-chat3Descarga 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.
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.0Go las descarga junto con lo que necesitan y termina con estas líneas:
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.04Escribe 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.
// 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 yety no se envía. - Lee la dirección del nodo de bootstrap del flag
-bootstrap, y127.0.0.1:7447es el valor por defecto.-listenes la dirección en la que escucha:127.0.0.1:0por defecto, que lo deja en tu ordenador; usa:0para 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-onlybusca sin anunciarse. -relayy-relay-keyindican 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:
go install github.com/ciranda-dev/kolo-node/cmd/kolo-node@v0.1.0Puede 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:
export PATH="$PATH:$(go env GOPATH)/bin"$env:Path += ";$env:USERPROFILE\go\bin"export PATH="$PATH:$(go env GOPATH)/bin"Arranca el nodo solo en tu ordenador, con su clave en una carpeta temporal nueva:
kolo-node run -listen 127.0.0.1:7447 -identity "$(mktemp -d)/node.key" -first$dir = New-Item -ItemType Directory -Path (Join-Path $env:TEMP "kolo-node-$(Get-Random)")
kolo-node run -listen 127.0.0.1:7447 -identity (Join-Path $dir.FullName "node.key") -firstkolo-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:
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=0Deja 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:
go run .La primera vez tarda un momento en compilar. Después el peer imprime su nombre y espera:
18:51:59 me 19353b70
18:51:59 joined "chat", type a line and press Enter7Arranca 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:
cd kolo-chatgo run .En pocos segundos los dos peers se encuentran. El Terminal 3 muestra:
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:
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:
hello from terminal 2Aparece en el Terminal 3, junto al nombre del peer que la envió:
18:52:23 <19353b70> hello from terminal 2Ahora responde desde el Terminal 3:
hi, terminal 3 hereY el Terminal 2 muestra:
18:52:31 <ffdabb7a> hi, terminal 3 here9Páralo todo
Pulsa Ctrl-C en el Terminal 3. Ese peer se detiene, y el Terminal 2 se da cuenta:
18:52:46 peer ffdabb7a lost: koloswarm: connection lostPulsa 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:
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=stoppedDos 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:
kolo-node run -listen :7447 -identity "$HOME/kolo-node/node.key" -firstDesde cada ordenador, comprueba que el puerto está abierto y arranca el chat escuchando en todas las interfaces:
kolo-node check 203.0.113.10:7447go run . -listen :0 -bootstrap 203.0.113.10:7447Qué 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-onlyallí: 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:
mkdir kolo-relay-server && cd kolo-relay-server && go mod init kolo-relay-servergo get github.com/ciranda-dev/kolo-id@v0.1.0 github.com/ciranda-dev/kolo-relay@v0.1.0Guarda 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:
// 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:
go run . -listen :7448Muestra 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:
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:
14:52:42 reserved on the relay
14:54:37 peer 8b4cc656 connected (through the relay)
14:54:50 <8b4cc656> helloEl relay solo se usa porque
pasaste -relay; nada recurre a él por su cuenta.
Qué acaba de pasar
- Cada peer se unió al topic
chata 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.