Nodes & mesh

P2P participation and public map presence are related but separate. The P2P process exchanges peer and block data; the public mesh API contains only coarse, opt-in telemetry and never exposes operator IP addresses.

GET/api/mesh

Public peer list plus live Genesis health overlay for maps and status UIs.

bash

curl -fsS https://grid-compute.com/api/mesh | jq '{phase, stats, genesis, peers: .peers[:5]}'

peer object

{
  "id": "node_macmini",
  "label": "MacNode",
  "class": "S",
  "region": "NA-W",
  "status": "offline",
  "role": "peer",
  "joinedAt": "2026-07-17T17:04:12.138Z",
  "lastSeen": "2026-07-18T04:14:57.178Z",
  "lat": 37.5,
  "lng": -122.5
}

Run the P2P peer

bash

# Genesis bootstrap is automatic
grid peer --name garage --with-bench

# Bind a different local listener
grid peer --name garage --listen 0.0.0.0:9901

# Add a known peer without removing Genesis
grid peer --name garage --connect peer.example:9900

The P2P protocol performs an authenticated hello, ping/pong RTT measurement, peer gossip, signed-truth refresh, ban enforcement, and block replication. The canonical Genesis endpoint is omitted only with --no-genesis, which is intended for controlled testing or the Genesis host itself.

Public map status is live data. A non-Genesis peer is marked offline when its location heartbeat is more than 60 seconds old. Genesis status comes from an HTTPS health check, not a stale map record.

Mesh ping (write)

POST/api/mesh/ping

Location-only heartbeat. Requires webhook auth in production. Body is allowlisted — nested objects and banned keys are dropped.

GET/api/mesh/ping

Machine-readable schema: accepted fields, filters, auth header name.

POST body

Field	Required	Notes
nodeId	yes	[a-zA-Z0-9_-]{2,64}
lat / lng	yes	WGS84 floats (quantized server-side)
label	no	Alnum + limited punctuation; no HTML
class	no	S \| M \| L
region	no	A-Z0-9_- only
status	no	online \| syncing \| idle \| offline

bash

curl -sS -X POST https://grid-compute.com/api/mesh/ping \
  -H 'content-type: application/json' \
  -H "authorization: Bearer $GRID_WEBHOOK_SECRET" \
  -d '{
    "nodeId": "node_a1b2c3d4",
    "label": "garage",
    "class": "S",
    "region": "NA-W",
    "status": "online",
    "lat": 37.7,
    "lng": -122.4
  }'

Server filters

Allowlist keys only
Max body ~4 KB
No IPs, hostnames, nested objects
Label sanitized against HTML/script patterns

A successful ping does not register a name on registry.grid. Listing requires paid activation. Globe coordinates should be operator-configured — never reverse-DNS or IP-geolocate silently.

CLI

When ~/.grid/env has GRID_WEBHOOK_SECRET and globe lat/lng, the node may fire-and-forget pings on start / heartbeat.

bash

# ~/.grid/env (operator machine only)
GRID_SITE_URL=https://grid-compute.com
GRID_WEBHOOK_SECRET=…   # same secret as Worker
GRID_GLOBE_LAT=37.7
GRID_GLOBE_LNG=-122.4
GRID_GLOBE_REGION=NA-W