Skip to content

Connections

Your node speaks to other nodes over several transports, with the same messaging layer on top. No Kunuleco server sits in the middle of a conversation. On a local network your nodes talk straight to each other, and across the internet they go over Veilid, Tor or IPFS, whose relays are run by other people and carry traffic they cannot read.

The transports

Transport Scope What it is for
mDNS and direct TCP Local network Same Wi-Fi or LAN. Nodes find each other with no setup
Veilid Internet Private routes that cross NAT without port forwarding
Tor Internet A persistent .onion address, so a node behind NAT can still be reached
IPFS Internet Tunnels through the IPFS network, found by DHT routing

The messaging layer on top is called CapTP. It is the same whichever transport carries it, so the rest of the node does not need to know how the bytes travelled.

This is also why nodes on one LAN keep working with no internet at all. They find each other over mDNS and carry on.

The order the node tries them in

There is no single priority list. The order depends on whether you are making first contact with someone or sending to someone you are already connected to.

First contact, join. The node first looks for a live LAN session to that person. If there is none, it tries Veilid, then Tor, then IPFS, one at a time, and stops at the first one where the other node proves who it is and answers the join. A join by name (join mira#7K2QX9 lobby) has one more step. If all of those fail, it tries every address in their record at the same time and keeps whichever connects first. A join by short code does not take that last step. A join with an in-person seed from meet tries the LAN addresses in the seed, all at once.

Sending to someone you are connected to. A tell uses a connection that already exists. It tries the LAN session first, then any other live CapTP session with that person, then Tor, then Veilid. It never opens a new connection. If none of those is up, the message goes to your outbox. Speech in a presence goes to the other members in the same order, and Tor comes before Veilid on purpose, because a Veilid route can drop a message without saying so.

You can steer this for testing. transport disable <mdns|ipfs|veilid|tor> makes join skip a transport, and transport force <name> makes join use only that one until you run transport force none.

The exact order, with the source lines, is in Reference: Transports.

What each transport protects

A local-network sighting is only a hint. Whatever mDNS announces, the signed CapTP hello decides who the peer is, and a node that cannot prove the name it claims is refused.

On the LAN, and on any direct TCP dial, CapTP runs over plain TCP. Every message is signed, so it cannot be altered or forged, but it is not encrypted, and anyone on the same network can read it (TPT-12). Veilid, Tor and IPFS carry the traffic encrypted between the two nodes. The node at each end reads it, and there is no end-to-end message encryption yet.

Tor is for reachability, not for hiding where your node is. Kunuleco uses Tor so that a node behind NAT can still be reached, and it makes no location-privacy promise. Every hello a node sends, including one sent over Tor, carries its IPFS (kubo) addresses, so a peer that reaches your node over Tor can learn where it is on the network. This is a recorded non-goal (TPT-105, ruled 2026-09-30), and it may be revisited later.

Local network (mDNS)

  1. Your node announces a _kunuleco._tcp.local. service.
  2. The announcement carries your handle (Name#TAG) and the CapTP port to dial, 4243 by default. None of it is signed.
  3. Another node on the LAN sees it and dials that port.
  4. The two nodes exchange signed hellos, and the hello decides who is there.

Two nodes that discover each other may both dial at once. CapTP merges the two connections into one session. Nothing listens on port 4242 any more.

Veilid

Veilid carries messages over private routes. Your node talks to a local veilid-server, creates a route, and shares it through an invite or the bootstrap registry. The node refreshes its route every two minutes. Veilid works through NAT and carrier-grade NAT with no port forwarding.

Tor

Tor gives your node a persistent onion service. The .onion address stays the same across restarts because its key is stored with your identity. A peer connects to it through Tor's SOCKS port, and the result is a real TCP connection rather than Veilid's message routes. Expect more delay than on the other transports.

IPFS

Your node announces itself on the kunuleco:discovery PubSub topic and carries CapTP through libp2p tunnels. To reach a peer's IPFS node it tries a known IP address first, then DHT routing, then a circuit relay.

Short codes

A short code like tiger-castle-7 is a lookup key. Behind it sit your handle, your verify key, the presence it invites to, and whichever internet endpoints your node has (a Veilid route, a Tor address, an IPFS peer ID). The code is registered with and resolved by a small directory service at kunul.eco. The directory learns that a code maps to your endpoints and never sees your messages. Anyone holding a code can use it, so treat it like a door code.

You hand someone a code, and they join it. The node they reach must still prove who it is in its signed hello. For an in-person connection with no internet, meet hands over the same information as a kunul1… seed and QR code, and it skips the directory entirely. Short codes are the one part of this page that needs the internet.

When someone is offline

A tell is saved to your chat history. If your friend is not connected, the message waits in your outbox (outbox lists it). When your friend comes back on a direct CapTP session, such as the LAN, the node sends what is queued by itself. outbox flush retries everything now.

Seeing your own connectivity

Command Use it to
transport See which transports are running and how many peers each has
ping <user> See which transports have a live connection to that person right now. It sends nothing
friends online Try to reach each of your contacts and report which transport answered
/network (client) Watch the live network view

More diagnostics are under help debug.