ARRR Network

Run a Node ​

This guide is for node providers: people who run a machine that hosts rooms for the apps built on the network. The node software is open source: https://github.com/m0dE/arrr-node.

A node does nothing on its own. It registers with the cloud service at https://cloud.arrr.fun, which is what sends clients to it and connects it to the other nodes. To join the public mesh you need an account there and a node token from the cloud console there.

Requirements ​

  • Node.js 18 or newer.
  • A public address. The service calls the node back to verify it, browsers open WebSockets to it, and other nodes relay through it. Behind a home router that means forwarding the port, or running a tunnel (Cloudflare Tunnel, ngrok, Tailscale Funnel) that gives you a public hostname with TLS.

1. Log in at cloud.arrr.fun ​

Go to https://cloud.arrr.fun and create an account (or log in). Choose the node provider side; you can switch later.

2. Mint a node token ​

On the Nodes page click Create token. The token looks like arrrn_… and is shown once. It is stored hashed, so copy it now. One token per machine is a good habit: it lets you revoke a single node without touching the others.

3. Start the node with it ​

bash
git clone https://github.com/m0dE/arrr-node.git
cd arrr-node
npm install
cp .env.example .env     # then fill in the values below
npm start

npm start builds and runs the node. npm run dev runs from source with a file watcher. Put these in .env (or export them):

bash
ARRR_NODE_TOKEN=arrrn_…                      # from the cloud console → Nodes
CENTRAL_SERVICE_URL=https://cloud.arrr.fun    # the public network
NODE_NAME="My node"                           # label in the console and dashboard
NODE_PORT=8001
NODE_PUBLIC_URL=wss://node.example.com/ws     # where browsers connect
NODE_API_PUBLIC_URL=https://node.example.com  # where the service and peers reach the HTTP API
VariableDefaultNotes
ARRR_NODE_TOKEN(unset)Token from the cloud console's Nodes page. Registers the node under your account. The public service refuses nodes without one.
CENTRAL_SERVICE_URLhttp://localhost:9001The cloud service to register with. https://cloud.arrr.fun for the public network.
NODE_NAMENodeLabel shown in the console and dashboard.
NODE_PORT8001Port to listen on.
NODE_PUBLIC_URLws://localhost:$NODE_PORT/wsWhere browsers connect. Must be reachable from the internet.
NODE_API_PUBLIC_URLhttp://localhost:$NODE_PORTWhere the service and other nodes reach this node's HTTP API. Usually the same host as above with http(s):// and no /ws.
NODE_IDephemeralLeave unset. A fresh id per process is what lets the service replace a restarted node's stale registration.

What happens when it starts ​

  1. The node listens on NODE_PORT and posts its id, name and URLs to the service, with ARRR_NODE_TOKEN as a bearer token.
  2. The service calls back NODE_API_PUBLIC_URL/api/auth/verify to check that the process at that address is the one that asked. If that URL is not reachable from the service, registration fails here; this is the step that catches a missing port-forward.
  3. The service answers with a validation key. The node uses it to verify the join tokens clients present, and the mesh tokens other nodes present.
  4. Every ten seconds the node heartbeats. If the service has forgotten it (after a restart, say) it registers again by itself.

A refused registration is logged with the service's reason and retried every five seconds, so a token you create in the console after the node started is picked up without a restart.

GET /health on the node reports what it is holding. GET /api/stats is what the dashboard reads.

4. Watch it on the dashboard ​

Once registered, your node appears on the console's Nodes page under your account, and on the live mesh dashboard at https://cloud.arrr.fun/dashboard (log in first). The dashboard shows every node in the mesh, the rooms each one is hosting, and the links between them.

Revoking a token ​

Delete the token on the Nodes page. The node it belongs to is refused on its next registration; a running node keeps going until it next has to register (a restart, or the service forgetting it). Mint a new token and restart the node with it to bring that machine back.

Developing against a local service ​

Run the cloud service locally (npm run dev in arrr-cloud, port 9001) and start the node with no token and no public URLs. The local service's default NODE_REGISTRATION=open accepts it.

Next steps ​