Skip to content

Transports Guide

Check and manage the network transports Kunuleco uses.

Commands here are node verbs. Type them as shown over SSH, or in the Urchin client's command mode (add / in chat mode). Commands that start with / exist only in the client.

Transport Overview

Transport Purpose Notes
mDNS Local network discovery Built into the node. A sighting is a hint, and the signed hello decides who the peer is
IPFS Content storage, such as media The node reports it as impaired as a peer transport in this build
Veilid Internet connectivity through private routes, without port forwarding Installed and started for you
Tor Reachability across NAT (not location privacy) Installed and started for you

The Urchin setup wizard installs IPFS (kubo), Veilid and Tor, and the node starts all three when it starts. If one fails to start, the node keeps running without it and says so in its log, for example [WARN] Tor not available - onion services disabled.

The CapTP messaging layer is the same whichever transport carries it.

Check Transport Status

transport
@node_processes

transport shows the state of mDNS, IPFS, Veilid and Tor, and whether any transport is disabled or forced. @node_processes shows which daemons are running. In the Urchin client, /network opens a live network view.

mDNS (Local Network)

How It Works

mDNS announces your node on the local network. No configuration is required.

  • Service: _kunuleco._tcp.local.
  • Port: 4243 (the CapTP port, which peers dial)

A sighting on the local network only starts a dial. The signed CapTP hello decides who the other node is. Nothing listens on port 4242 any more.

Verify mDNS

@discover
@peers

@discover lists the peers discovered, and marks one as verified only after a signed hello. @peers lists connected peers across all transports.

Firewall Requirements

Allow:

  • UDP 5353 (mDNS multicast)
  • TCP 4243 (CapTP connections)

IPFS

How It Works

The node runs its own kubo daemon. On an installed node the binary is in the installation's bin/ directory and the repository is under data/ipfs. The node sets the kubo options it needs (such as PubSub and P2P stream mounting) itself.

Media uploads (media upload) are pinned to IPFS. As a transport for reaching peers, IPFS is marked impaired in this build. The daemon runs, but peer traffic does not cross it, and an update to the node is what will change that.

Verify IPFS

@ipfsid
@ipfspeers

@ipfsid shows the node's IPFS peer ID and addresses. @ipfspeers shows its swarm peers.

Isolated Instance

The Kunuleco installer uses its own ports, so an installed node does not collide with a system IPFS:

Feature Default Kunuleco
API 5001 15001
Swarm 4001 14001
Gateway 8080 18080

Troubleshooting IPFS

  • Check ipfs-daemon.log in the node's logs directory.
  • The current kubo version has a known memory growth issue. Restarting Urchin clears it.
  • To check and repair the installed kubo, see the installer's command line.

Veilid

How It Works

The node starts its own veilid-server and talks to it over Veilid's API, on port 15959 on an installed node (5959 without the installer's config.json). You do not start Veilid yourself.

Verify Veilid

@veilidstatus
@vpeers

@veilidstatus shows the Veilid connection status. @vpeers shows Veilid peers.

Troubleshooting Veilid

Not connecting:

  1. Run transport and @veilidstatus
  2. Wait for Veilid to attach to its network, which takes longer on the first start
  3. Check veilid-daemon.log in the node's logs directory

Time sync:

Veilid requires accurate system time. Turn on network time:

# Linux
sudo timedatectl set-ntp true

# macOS
sudo sntp -sS time.apple.com

Veilid is not yet available for Intel Macs.

Tor

How It Works

The node starts its own Tor, with its own torrc under the installation's data/tor directory. You do not install or configure a system Tor.

Tor gives your node a persistent .onion address, which peers can reach across NAT. It does not hide where your node is. Every hello your node sends carries its IPFS addresses.

Verify Tor

@torstatus
@toraddress

@torstatus shows the Tor status. @toraddress shows your .onion address.

Isolated Instance

Kunuleco uses its own ports:

Feature Default Kunuleco
SOCKS 9050 19050
Control 9051 19051

If your Tor asks for a control-port password, set TOR_CONTROL_PASSWORD for the node. See the configuration reference.

Troubleshooting Tor

Can't establish circuit:

  1. Run @torstatus
  2. Check the control port answers: nc -z localhost 19051
  3. Check tor-daemon.log in the node's logs directory
  4. The network may be blocking Tor

How a Connection Picks a Transport

When your node connects to a peer, it tries the peer's published endpoints on every available transport at once and keeps the first connection that succeeds.

Force a Specific Transport

The node's owner can pin the next join to one transport:

transport force veilid
transport force none

transport force <mdns|ipfs|veilid|tor> applies to the next join. transport force none clears it.

Disable a Transport

If a transport is causing issues, the node's owner can turn it off and on again:

transport disable veilid
transport enable veilid
transport enable all

transport disable and transport enable take mdns, ipfs, veilid or tor, and transport enable all turns every transport back on and clears a forced one. These settings apply to the whole node, for every session, and last until the node restarts. Only the node's owner can change them.