Este é o primeiro passo: você constrói um chat que roda no seu terminal.
Em uns dez minutos, você vai rodar três programas no seu próprio computador: um nó de bootstrap e duas cópias de um pequeno chat. Os dois chats se encontram, se conectam diretamente e enviam um ao outro o que você digita.
Tudo fica no seu computador, no endereço 127.0.0.1. Você não precisa de
conta nem de nenhum servidor nosso. Quando funcionar, a última seção leva o
mesmo chat para dois computadores em redes
diferentes.
1Confira o que você precisa
Você precisa do Go 1.26 ou mais recente e de três janelas de terminal. Se o Go ainda não estiver instalado, instale para o seu sistema:
Baixe o instalador para macOS (o arquivo .pkg) em
go.dev/dl e execute o arquivo. Se você usa o Homebrew,
também dá para instalar assim:
brew install goBaixe o instalador para Windows (o arquivo .msi) em
go.dev/dl e execute o arquivo. Ele adiciona o Go ao
seu PATH. Depois abra o PowerShell.
Use o pacote golang da sua distribuição se ele for da versão 1.26 ou mais
recente. Se não for, baixe o arquivo .tar.gz em
go.dev/dl e siga os passos para Linux em
go.dev/doc/install.
Confira a sua versão do Go:
go versionVocê deve ver a versão 1.26 ou uma mais recente, por exemplo:
go version go1.27.3 darwin/arm64Agora abra três janelas de terminal e deixe uma ao lado da outra:
Abra o app Terminal e aperte Cmd+N duas vezes para ter mais duas janelas.
Abra o PowerShell três vezes, ou abra o Windows Terminal e aperte Ctrl+Shift+T duas vezes para ter mais duas abas.
Abra o seu app de terminal e aperte Ctrl+Shift+N duas vezes para ter mais duas janelas (na maioria dos terminais, Ctrl+Shift+T abre abas).
Neste tutorial, elas se chamam Terminal 1 (o nó de bootstrap), Terminal 2 e Terminal 3 (os dois peers do chat).
2Crie uma pasta e um módulo
No Terminal 2, crie uma pasta para o chat e entre nela:
mkdir kolo-chat && cd kolo-chatmkdir kolo-chat; cd kolo-chatmkdir kolo-chat && cd kolo-chatDepois crie um módulo Go dentro dela:
go mod init example.com/kolo-chatO Go responde:
go: creating new go.mod: module example.com/kolo-chat3Baixe as bibliotecas
Ainda no Terminal 2, adicione as três bibliotecas do Kolo que o chat usa: a kolo-swarm, para encontrar peers e se conectar a eles, a kolo-id, para a chave de cada peer, e a kolo-relay, para o relay que você pode adicionar depois.
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.0O Go baixa as três com o que elas precisam e termina com estas linhas:
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.04Escreva o programa
Crie um arquivo chamado main.go na pasta kolo-chat e cole este programa
nele. Ele entra em um topic chamado chat, imprime cada linha que outro
peer envia e envia cada linha que você digita para todos os peers com 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)
}
}Algumas coisas que vale a pena saber sobre ele:
- Cada execução cria uma chave nova na memória, então cada peer ganha um nome novo toda vez que você o inicia. O nome dele são os 4 primeiros bytes da sua chave pública.
- Uma linha que você digita antes de haver algum peer conectado mostra
no peer connected yete não é enviada. - Ele lê o endereço do nó de bootstrap da flag
-bootstrap, e127.0.0.1:7447é o valor padrão.-listené o endereço em que ele escuta:127.0.0.1:0por padrão, o que o mantém no seu computador; use:0para alcançar outros computadores. - Ele busca o topic de novo a cada 15 segundos (
-lookup-every), então encontra peers que entram depois.-lookup-onlybusca sem se anunciar. -relaye-relay-keyindicam um servidor kolo-relay para tentar quando uma conexão direta falha. Sem eles, nenhum relay é usado.- O que outro peer envia não é confiável: o programa lê no máximo 4.096 bytes por mensagem e remove os caracteres de controle antes de imprimir.
5Inicie um nó de bootstrap no Terminal 1
O nó de bootstrap é o primeiro endereço que os peers procuram. Ele ajuda os peers a se encontrarem e depois sai do caminho: as suas mensagens nunca passam por ele.
No Terminal 1, instale o kolo-node:
go install github.com/ciranda-dev/kolo-node/cmd/kolo-node@v0.1.0O Go pode imprimir algumas linhas go: downloading e depois mais nada. O
programa vai para a pasta bin do Go. Se no próximo passo o seu shell não
encontrar o kolo-node, adicione essa pasta ao seu PATH neste terminal:
export PATH="$PATH:$(go env GOPATH)/bin"$env:Path += ";$env:USERPROFILE\go\bin"export PATH="$PATH:$(go env GOPATH)/bin"Inicie o nó só no seu computador, com a chave dele em uma pasta temporária nova:
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 inicia uma rede nova: este nó não tem outros nós de entrada para entrar. Ele imprime três linhas e continua rodando. Os seus horários e a sua chave
vão ser diferentes:
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=0Deixe o Terminal 1 aberto.
6Inicie o primeiro peer no Terminal 2
No Terminal 2, dentro da pasta kolo-chat, rode o chat:
go run .Na primeira vez, ele leva um momento para compilar. Depois o peer imprime o nome dele e fica esperando:
18:51:59 me 19353b70
18:51:59 joined "chat", type a line and press Enter7Inicie o segundo peer no Terminal 3
No Terminal 3, vá para a mesma pasta kolo-chat (use o caminho onde
você a criou) e rode o chat de novo:
cd kolo-chatgo run .Em poucos segundos, os dois peers se encontram. O Terminal 3 mostra:
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)A porta depois de 127.0.0.1 vai ser outra. O Terminal 2 ganha uma linha
com o nome do novo peer, e pode mostrar uma linha found para ele na
próxima busca:
18:52:07 peer ffdabb7a connected (direct)8Digite uma linha e veja a linha chegar
No Terminal 2, digite uma linha e aperte Enter:
hello from terminal 2Ela aparece no Terminal 3, ao lado do nome do peer que a enviou:
18:52:23 <19353b70> hello from terminal 2Agora responda pelo Terminal 3:
hi, terminal 3 hereE o Terminal 2 mostra:
18:52:31 <ffdabb7a> hi, terminal 3 here9Pare tudo
Aperte Ctrl-C no Terminal 3. Esse peer para, e o Terminal 2 percebe:
18:52:46 peer ffdabb7a lost: koloswarm: connection lostAperte Ctrl-C no Terminal 2. Depois aperte Ctrl-C no Terminal 1; o nó se despede com estas linhas e fecha:
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=stoppedDois computadores em redes diferentes
O mesmo programa funciona entre dois computadores, por exemplo um em casa e
outro no trabalho. Os exemplos do Kolo prontos, e qualquer programa que chame
Bootstrap(ctx, nil) sem lista, usam os nós de entrada públicos que a
Ciranda mantém no ar, então não precisam de configuração. Este chat recebe
o nó de entrada de -bootstrap, então aqui você roda um nó de entrada
próprio: uma terceira máquina que os dois computadores alcancem, um host com
um endereço IPv4 público, como um VPS pequeno. Os passos usam
203.0.113.10 como o endereço dele; use o seu.
Nesse host, instale o kolo-node como no passo 5, abra a porta UDP 7447 no firewall dele (e no do provedor, se houver) e inicie o nó em todos os seus endereços:
kolo-node run -listen :7447 -identity "$HOME/kolo-node/node.key" -firstEm cada computador, confira se a porta está aberta e inicie o chat escutando em todas as interfaces:
kolo-node check 203.0.113.10:7447go run . -listen :0 -bootstrap 203.0.113.10:7447O que as linhas querem dizer:
found <peer> at <address>, connecting: a busca retornou o outro peer, e o chat está abrindo uma conexão com ele.peer <peer> connected (direct): os dois computadores falam diretamente; o host só ajudou os dois a se encontrarem.could not reach <peer> directly (...): não há caminho direto. Os dois lados enviaram pacotes para abrir um (hole punching), e as redes os descartaram.join: ...ao iniciar: o chat não conseguiu anunciar nem buscar o topic. Se o que falha nessa rede é o anúncio, tente-lookup-onlyali: esse chat ainda encontra o outro, mas não pode ser encontrado, então inicie ele por último.
Uma rede corporativa ou uma VPN pode bloquear o anúncio, o hole punching ou os dois. Aí você precisa de um relay.
Um relay para quando não há caminho direto
Esta parte foi testada entre dois computadores pela internet, por meio de um relay em um host na nuvem.
O kolo-relay repassa pacotes cifrados entre dois peers que não conseguem se alcançar. Ele não consegue lê-los: a própria conexão kolo-secure dos peers vai dentro. No mesmo host público, crie uma segunda pasta e um módulo para o servidor do 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.0Salve isto como main.go. Ele guarda a chave em relay.key (ou no
arquivo que você passar com -identity), então a chave não muda entre
reinícios:
// 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()
}Abra a porta UDP 7448 no host e inicie o relay:
go run . -listen :7448Ele mostra uma linha, relay on <address>, key <key>, em que a chave tem
64 caracteres hexadecimais. Inicie os dois chats com o endereço do relay e
essa chave completa:
go run . -listen :0 -bootstrap 203.0.113.10:7447 -relay 203.0.113.10:7448 -relay-key <relay key>Cada chat mostra reserved on the relay. Quando uma conexão direta falha,
o chat mostra trying <peer> through the relay, depois o peer se conecta
pelo relay e as linhas vão nos dois sentidos. Desse teste:
14:52:42 reserved on the relay
14:54:37 peer 8b4cc656 connected (through the relay)
14:54:50 <8b4cc656> helloO relay só é usado porque
você passou -relay; nada recorre a ele sozinho.
O que acabou de acontecer
- Cada peer entrou no topic
chatpor meio da DHT do nó de bootstrap: ele se anunciou lá e procurou o topic. Foi assim que o segundo peer encontrou o primeiro. Veja Topics. - Depois de se encontrarem, os dois peers se conectaram diretamente. O nó de bootstrap só ajudou os dois a se conhecerem; as suas mensagens nunca passaram por ele.
- A conexão é um canal criptografado ligado à chave de cada peer, feito pela kolo-secure. Cada lado conhece a chave completa do peer com quem fala. Veja Peers.
- Nos primeiros passos tudo rodou em
127.0.0.1, então só programas do seu computador podiam entrar. Entre computadores, o seu próprio nó de bootstrap roda em um host que os dois alcançam e cada chat escuta em:0; a página do kolo-node explica como rodar o nó de verdade.
Próximos passos
- Leia a página da kolo-swarm: a API, os limites e o que cada evento significa.
- Leia os Conceitos: peers, topics, logs, réplicas, exclusão e o relay, uma página curta para cada.
- Veja o que mais você pode construir em kolo.ciranda.dev: Casos de uso.