Your first fleet
In this tutorial you run two FleetMesh nodes on your own machine, enrol both in a fleet that belongs to you, and run a command on one of them from your fleet key alone. It takes about ten minutes and needs no server, no domain and no account anywhere.
You need meshnode and meshctl installed (Install), three
terminal windows, and the ports 7101 and 7102 free.
What you are building
you (operator.key)
| meshctl: enrol tokens, the fleet roster, remote commands
v
ws://127.0.0.1:7101 <- the first node's relay face, which every
| | message in this tutorial passes through
first second
(node) (node)
A node talks to the world through Nostr relays. Every node also serves a relay of its own, its face, so the first node’s face is all the relay this tutorial needs. A real fleet uses public relays instead, and nothing else changes.
1. Make the first node
Work in a fresh directory:
mkdir fleetmesh-tutorial && cd fleetmesh-tutorial
Create the first node. --face-port is where its relay face listens, and
--relay points the node at that same face:
meshnode init first --name first --face-port 7101 --relay ws://127.0.0.1:7101
init makes the node’s keys and configuration in the directory first/, and
mines its descriptor: the signed event that tells other nodes what this
node is and how to reach it. Mining takes a few seconds. The output ends by
saying no relay accepted the descriptor yet. That is expected, because the
relay is the node’s own face and the node is not running. The first run
publishes it.
In your second terminal, in the same fleetmesh-tutorial directory, start
the node and leave it running:
meshnode run first
It prints a line for every part of the node as it starts, then
relay ws://127.0.0.1:7101 acknowledged the subscription.
Back in the first terminal, ask the node how it is:
meshnode status first
2. Make the second node
The second node gets its own face on port 7102, but uses the first node’s face as its relay:
meshnode init second --name second --face-port 7102 --relay ws://127.0.0.1:7101
This time the descriptor goes out straight away (sent ws://127.0.0.1:7101),
because that relay is running.
Start it in your third terminal:
meshnode run second
3. Make your operator key
A fleet is a set of nodes that answer to one key: yours. It is a Nostr secret key, 32 random bytes in hex. Make one and keep it private:
openssl rand -hex 32 > operator.key
chmod 600 operator.key
Neither node knows this key yet. Both are running with no operator at all:
meshnode whoami first
The operator field is empty. Save each node’s public key in a shell
variable for the next steps:
FIRST=$(meshnode whoami first | awk '/^pubkey/ {print $2}')
SECOND=$(meshnode whoami second | awk '/^pubkey/ {print $2}')
echo "$FIRST $SECOND"
4. Enrol both nodes in your fleet
Enrolment is two halves. You mint a token with your key, bound to one node’s public key, and the node accepts it. A token minted for one node is refused by every other node, so it is safe to hand over.
meshctl fleet token "$FIRST" --key-file operator.key > first.token
meshctl fleet token "$SECOND" --key-file operator.key > second.token
cat first.token
Now each node accepts its own token:
meshctl enrol "$(cat first.token)" --dir first
meshctl enrol "$(cat second.token)" --dir second
Each node republishes its descriptor and sends a heartbeat. meshnode whoami first now names your key as its operator.
5. Keep a roster of your fleet
Who owns which node is private. A node’s public descriptor does not say who its operator is, so a stranger reading the relay cannot list your fleet. You keep the list yourself, as a roster encrypted to your own key and stored on the relay:
meshctl fleet add "$FIRST" --key-file operator.key --relay ws://127.0.0.1:7101 --label first
meshctl fleet add "$SECOND" --key-file operator.key --relay ws://127.0.0.1:7101 --label second
Read it back:
meshctl fleet list --key-file operator.key --relay ws://127.0.0.1:7101
Both nodes are listed, with the labels you gave them. Their state shows
unknown until their next heartbeat comes round.
6. Run a command on a node, from your key
You do not need a node of your own, a login, or SSH to run a command on a node
in your fleet. meshctl send seals the request with your key, publishes it to
the node’s relay, and opens the node’s sealed answer:
meshctl send "$FIRST" health --key-file operator.key --relay ws://127.0.0.1:7101
The answer is the first node’s own health report: its relays, its inbox, its capacity, and whatever trouble it has (none). The request travelled as a NIP-59 gift wrap: the relay saw a sealed event, not the command.
Try another command, from the same key:
meshctl send "$SECOND" status --key-file operator.key --relay ws://127.0.0.1:7101
Now try it with a key that is not yours to use:
openssl rand -hex 32 > stranger.key
chmod 600 stranger.key
meshctl send "$FIRST" health --key-file stranger.key --relay ws://127.0.0.1:7101
The node refuses: refused not_operator. A command runs only for the node’s
operator, or for a key that holds a grant from it.
7. Clean up
Stop each node with Ctrl-C in its terminal. Everything this tutorial made is
in the fleetmesh-tutorial directory; delete it when you are done.
What you did
Made two nodes, each with its own keys, descriptor and relay face.
Made an operator key and enrolled both nodes under it with tokens bound to each node’s key.
Kept a private, encrypted roster of your fleet on the relay.
Ran commands on your nodes over
control/1.0, sealed with your key.
Next: A browser leaf app puts a web page on the mesh.