Skip to main content

Join the network

A freshly installed node is private. It indexes and answers for you, and announces nothing. Joining is the deliberate step where two machines start sharing indexes and agent memory.

Your identity​

Every node is an ed25519 keypair, generated on first run. The public half is the node ID; the private half signs what the node publishes.

gnarl identity show
Back up your data directory

The key lives in your data directory (~/.lucenia by default). Lose it and you lose the identity — peers that trusted the old node ID will not follow it to a new one.

Create a mesh​

gnarl mesh setup --mesh-name my-mesh --with-invite

This prints the gnarl start … command to run, and an invite token. Defaults worth knowing:

  • private scope with your mesh name
  • --replicas 2, so one machine can go down without taking your data with it
  • cloud bootstrap and relay on, so home NATs and CGNAT still join
  • --no-tls on localhost, so agent wiring and the Console work out of the box

Invite a peer​

Invites are pinned to a node ID, so a mesh name alone is not enough to join.

# they run this and send you the node id
gnarl status

# you run this and send them the token
gnarl mesh invite --mesh-name my-mesh --admit-peer <their-64-hex-node-id>

They redeem it:

gnarl mesh join --invite 'lucenia1.…'

…then run the start command it prints.

Confirm​

On both machines:

gnarl status

You want peers > 0. Across the internet, also look for the relay to be connected — a WAN join can take 30–60 seconds while bootstrap and relay settle.

What crosses the network​

Not your documents. Nodes index locally and match locally; what travels is the signed manifest of what a node can answer, the query, and whatever hits your own policy allows you to return. See Trust and verification.

Next​