PearData

Decentralized, P2P, real-time monitoring for the Pear / Holepunch ecosystem.

Each machine runs a lightweight PearMonitor agent. A Pear desktop client dials agents by public key and shows fleet + per-node live dashboards. Agents also expose an agent-compatible REST API (/api/v1, /api/v2, /api/v3) for scripts, Grafana, and Prometheus.

Built from the pear-app-template HyperDHT + protomux-rpc patterns used by PearDock-class apps (MIT template — not a copy of PearDock’s AGPL sources).

Plane	Stack
Transport	HyperDHT secret streams (Noise)
RPC	protomux-rpc + compact-encoding JSON
Metrics	1s collector → tiered buffers → push + query
AuthZ	Roles (viewer / operator / admin) + pd1. invites + admin seed
HTTP	agent-style REST on 127.0.0.1:19999
Desktop	Pear (pear-electron + pear-bridge + <pear-ctrl>)

---

Quick start

One-line installer (recommended)

curl -fsSL https://git.ssh.surf/snxraven/peardata/raw/branch/main/scripts/install.sh | bash

# Server only (Linux Bare + systemd → /opt/peardata)
curl -fsSL https://git.ssh.surf/snxraven/peardata/raw/branch/main/scripts/install.sh | bash -s -- --server --yes

# Desktop client only
curl -fsSL https://git.ssh.surf/snxraven/peardata/raw/branch/main/scripts/install.sh | bash -s -- --client --yes

From source

cd peardata
npm install

# Terminal A — agent (prints public key + REST URL)
npm run start:server

# Terminal B — REST smoke test
curl -s http://127.0.0.1:19999/api/v3/info | jq
curl -s 'http://127.0.0.1:19999/api/v3/data?chart=system.cpu&after=-30&points=30' | jq

# Terminal C — mint an operator invite (optional)
npm run mint-invite -- operator

# Terminal D — Pear / Electron desktop
npm start
# or: npm run start:client

In the UI, paste the agent public key (viewer) or a pd1. invite.
Paste SERVER_SEED for admin without an invite.

npm test
npm run healthcheck

---

Repository layout

peardata/
├── app.js / index.html / ui/   # Pear fleet dashboard
├── shared/                     # Protocol, metrics catalog, schema, crypto
├── spec/                       # Generated Hyperschema + HyperDB definitions
├── scripts/build-db.js         # Regenerate spec/ (`npm run build:db`)
├── server/                     # PearMonitor agent
│   ├── server.js               # DHT + HyperDB + pipeline + REST boot
│   ├── pipeline.js             # collector → store → anomaly → push
│   ├── db/                     # HyperDB model + Corestore + swarm replicate
│   ├── handlers/monitor.js     # Domain RPCs
│   ├── services/               # collector, store, warm-flush, anomaly, jobs
│   ├── rest/                   # agent-compatible HTTP API
│   └── core/ rpc/ utils/       # Auth, ACL, sessions (template)
├── client/                     # Multi-peer connection manager
├── docs/                       # Full documentation set
├── deploy/peardata.service     # systemd
└── test/

---

npm scripts

Script	Purpose
npm start	Pear desktop UI
npm run start:server	PearMonitor agent (P2P + REST)
npm run start:client	Electron desktop (packaged UI)
npm run make	Build Linux servers + all client arches
npm run make:server	Bare peardata-server (linux-x64 / linux-arm64)
npm run make:client	Electron clients (all 64-bit hosts)
npm test	brittle unit + integration
npm run mint-invite -- [role]	Offline pd1. invite
npm run build:db	Regenerate HyperDB spec/
npm run healthcheck	Liveness / remote ping
npm run soak	Load exercise

---

Auth model

Mode	How	Role
Viewer	Dial public key only	viewer (read + subscribe)
Capability	pd1. invite or HMAC token	granted role
Admin seed	HMAC proof from SERVER_SEED	admin
Allowlist	PEARDATA_ADMIN_KEYS	admin for listed peers

---

Documentation

Doc	Contents
Getting started	Install, agent, REST, desktop, systemd
Roadmap	MVP → advanced phases
Architecture	PearDock mapping, planes, modules
Protocol	RPC methods & pushes
Data model	Metrics, anomalies, health
REST API	/api/v1|v2|v3
Tech choices	Collector, charts, Bare maps
HyperDB storage	Warm history, peer links, swarm sync
Release	Binary host matrix + rolling CI
CI	Gitea / GitHub pipelines
Security	Threat model & hardening
Configuration	Environment reference

---

License

MIT — Pear ecosystem tooling starter.
(Peardock itself is AGPL; this project does not copy peardock source verbatim.)