Skip to content

Connecting Nodes Guide

Connect with other Kunuleco users.

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.

Connection Methods

Method When to Use
Invitation First-time connection with a new person
In person You are on the same network as them: meet
By handle You know their handle, such as mira#4Q7K2M
Local Discovery Same network, automatic

A handle is a name followed by # and six characters derived from the person's identity. Whichever way you connect, each node proves who it is with a signed hello, and that proof decides who the other side is.

Create an Invitation

invite garden

invite <presence> creates an invite to a presence. With no name it invites to your current presence, which is the lobby by default. The node shows an invite string of the form join <your handle> <presence> and, by default, a short code such as tiger-castle-7 to pass along as join tiger-castle-7. -noshort leaves the short code out. In a terminal it also draws a QR code of the invite string.

In the Urchin client, /invite-wiz mints an invite with a copy button.

Expiry and use limits for invites are not decided yet. A short code can stop resolving, and the invite string still works when it does.

Decide Who May Join

A ~presence you own is open to anyone who knows its name, by default. To make it invite-only and name the people who may join:

door garden invite
door garden invite alex#9T3HVB
door garden uninvite alex#9T3HVB
door garden open

door <presence> on its own shows the current setting. The invite is kept against the identity the person's connection proved, so someone else using the same name is refused. Only the presence's owner can change its door. The lobby is always open.

A room's door works differently and is not covered here.

Accept an Invitation

join tiger-castle-7
join mira#4Q7K2M garden

join takes a short code, or a handle and a presence name. Your node reaches the host and joins you to the presence. In the Urchin client, /join-wiz does the same from a dialog.

If the presence is invite-only and you are not invited, the host refuses and the reply begins Error: the host of garden refused the join.

Meet in Person

When you and the other person are on the same local network:

meet

meet shows a peer seed (a code starting kunul1) and a QR code. The other person runs join <seed> on their node, which then connects to yours directly over the LAN. The connection is checked against the identity the seed pins, and a seed from an older build is refused with its reason. The seed works only while your node stays on that network.

meet guest shows this node's address and a QR code, so a phone running the Urchin app can join it as a client.

See Who You Are Connected To

@peers
@discover

@peers lists connected peers across all transports. @discover lists everyone discovered, and marks a peer as verified only when a signed hello has proved who it is.

To check one peer:

ping mira#4Q7K2M

ping reports whether that peer is connected and over which transports.

Leave a Presence

leave garden

leave <presence> takes you out of a presence. With no name it leaves your current one.

There is no command that drops one peer's connection without blocking them. block <name> refuses the person and drops any open session with them, and unblock <name> undoes it. A block holds on the identity they proved, over any transport and after a reconnect.

Connect by Handle

@pconnect mira#4Q7K2M

@pconnect connects to a peer by their handle. It tries the peer's published endpoints on every transport at once and keeps the first that succeeds.

Local Network Discovery

On the same LAN, discovery is automatic through mDNS. A sighting on the local network is only a hint. Your node then dials the peer's CapTP port (4243 by default), and the signed hello decides who is there. @discover shows a peer as verified only after that.

Nothing listens on port 4242 any more. The firewall needs UDP 5353 (mDNS) and TCP 4243 (CapTP).

Manual Connection

If automatic discovery fails, the transport-level verbs connect one peer by hand. They are diagnostic tools, listed by help debug.

Using a Veilid Route

@veilidroute
@veilidconnect mira#4Q7K2M <route_blob>

@veilidroute shows your Veilid route blob to share. The other person passes it to @veilidconnect with your handle.

Using a Tor Address

@toraddress
@torconnect mira#4Q7K2M <onion_address>

@toraddress shows your .onion address. The other person connects with @torconnect and your handle. Tor gives reachability across NAT. It does not hide where your node is.

Connect the Client to Another Node

The Urchin client talks to one node at a time, your own by default. To use a different one:

/connect <host> [port]

The client keeps that node for next time. Its connection is encrypted, but the client cannot tell that it reached the right node until you record the node's trust bundle. Ask the node's operator to run @node_trust and send you the bundle, check its fingerprint with them by another route, and record it with /trust <bundle> [host]. /untrust [host] forgets it.

Connection Troubleshooting

Can't Connect via mDNS

  1. Verify you are on the same network by pinging the other machine's IP address from your system shell
  2. Check the firewall allows UDP 5353 and TCP 4243
  3. Run @discover and @netcheck on the node
  4. Check both nodes run the same version. A newer node can dial an older one over mDNS, but an older node cannot dial a newer one

Can't Connect via Veilid

  1. Run transport and @veilidstatus on the node
  2. Wait for Veilid to attach to its network, which takes longer on the first start
  3. Check the system clock is correct. Veilid needs accurate time

Can't Connect via Tor

  1. Run @torstatus on the node
  2. Check tor-daemon.log in the node's logs directory
  3. The network may be blocking Tor

Connection Drops

  1. Run transport to see each transport's state
  2. The node's owner can pin the next join to one transport with transport force <mdns|ipfs|veilid|tor>, and clear it with transport force none
  3. Check node.log in the node's logs directory

Managing Capabilities

After connecting, you can give someone access to one of your capsules, or take it away.

Grant Access

grant notes alex#9T3HVB read,write

grant <capsule> <identity> <caps> [--service <service>] grants capabilities on a capsule you own.

Revoke Access

revoke notes alex#9T3HVB

With no capabilities named, revoke removes them all.

View Grants

list grants notes