Skip to main content

Join the network

A freshly installed node is private. Joining is the deliberate step where you tell a set of peers what you are willing to answer.

Generate an identity​

Every node has a keypair. The public half is its node ID; the private half signs every manifest and every result the node returns.

gnarl identity create --label "gnarl-ops-1"
▸ node id    n1qh7f2m9x8p4vd6kkzq3r7wjn5tbc2a8
▸ key        ed25519 · stored in ~/.gnarl/identity.key
▸ backup     write this file down somewhere safe
Back up your key

Lose the private key and you lose the identity. Peers that trusted the old node ID will not follow it to a new one.

Join a public network​

gnarl join --network public

Bootstrap peers are resolved, your manifest is announced, and your node starts receiving queries it can answer.

▸ resolving   bootstrap.gnarl.dev
▸ peers       17 discovered · 12 reachable
▸ announcing  manifest 1 (2 indexes · 12,840 docs)
▸ joined      public

Join a private network​

Most operators run their own. A private network is a shared secret plus a set of bootstrap addresses — no registry, no central service.

gnarl join \
  --network acme-internal \
  --bootstrap gnarl-a.acme.internal:7420,gnarl-b.acme.internal:7420 \
  --psk-file ./acme.psk

Nodes without the pre-shared key cannot discover, query, or even confirm the existence of members.

Confirm you are answering​

gnarl node status
▸ node        n1qh7f…c2a8   up 4h12m
▸ network     acme-internal · 12 peers · 9 healthy
▸ serving     2 indexes · 12,840 docs · manifest 1
▸ queries     1,204 answered · p50 34ms · p99 210ms
▸ rejected    18 (policy) · 0 (unverified signature)

Leaving​

gnarl leave

Your manifest is withdrawn and peers stop routing to you. In-flight queries finish; nothing you hold is deleted.

Next​