347 lines
16 KiB
HTML
347 lines
16 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="en" data-theme="dark">
|
||
<head>
|
||
<!-- Theme: FOUC-safe bootstrap (localStorage peardata.site.theme) -->
|
||
<script>
|
||
(function () {
|
||
try {
|
||
var t = localStorage.getItem('peardata.site.theme');
|
||
if (t !== 'light' && t !== 'dark') t = 'dark';
|
||
document.documentElement.setAttribute('data-theme', t);
|
||
var meta = document.querySelector('meta[name="theme-color"]');
|
||
if (meta) meta.setAttribute('content', t === 'light' ? '#f3f5f8' : '#0a0c10');
|
||
} catch (e) {
|
||
document.documentElement.setAttribute('data-theme', 'dark');
|
||
}
|
||
})();
|
||
</script>
|
||
|
||
<meta charset="UTF-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
|
||
<title>How PearData Works · P2P fleet monitoring</title>
|
||
<meta name="description" content="Learn how PearData monitors hosts over peer-to-peer HyperDHT. Identity, hole punching, live metrics, alerts, QVAC, and security — no open ports required." />
|
||
<meta name="keywords" content="PearData P2P, HyperDHT, hole punching, monitoring, metrics, QVAC, observability, HoneyPeer" />
|
||
<meta name="author" content="HoneyPeer, LLC" />
|
||
<meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1" />
|
||
<meta name="googlebot" content="index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1" />
|
||
<meta name="theme-color" content="#34d399" />
|
||
<meta name="color-scheme" content="dark light" />
|
||
<meta name="application-name" content="PearData" />
|
||
<meta name="apple-mobile-web-app-title" content="PearData" />
|
||
<meta name="apple-mobile-web-app-capable" content="yes" />
|
||
<meta name="mobile-web-app-capable" content="yes" />
|
||
<meta name="msapplication-TileColor" content="#34d399" />
|
||
<meta name="msapplication-config" content="/assets/favicons/browserconfig.xml" />
|
||
<meta name="format-detection" content="telephone=no" />
|
||
<link rel="canonical" href="https://peardata.rest/learn/" />
|
||
<link rel="alternate" hreflang="en" href="https://peardata.rest/learn/" />
|
||
<link rel="alternate" hreflang="x-default" href="https://peardata.rest/learn/" />
|
||
|
||
<meta property="og:type" content="article" />
|
||
<meta property="og:site_name" content="PearData" />
|
||
<meta property="og:locale" content="en_US" />
|
||
<meta property="og:url" content="https://peardata.rest/learn/" />
|
||
<meta property="og:title" content="How PearData Works · P2P fleet monitoring" />
|
||
<meta property="og:description" content="Learn how PearData monitors hosts over peer-to-peer HyperDHT. Identity, hole punching, live metrics, alerts, QVAC, and security." />
|
||
<meta property="og:image" content="https://peardata.rest/assets/brand/og-image.png" />
|
||
<meta property="og:image:secure_url" content="https://peardata.rest/assets/brand/og-image.png" />
|
||
<meta property="og:image:type" content="image/png" />
|
||
<meta property="og:image:width" content="1200" />
|
||
<meta property="og:image:height" content="630" />
|
||
<meta property="og:image:alt" content="PearData: decentralized P2P monitoring on HyperDHT" />
|
||
|
||
<meta name="twitter:card" content="summary_large_image" />
|
||
<meta name="twitter:title" content="How PearData Works · P2P fleet monitoring" />
|
||
<meta name="twitter:description" content="Learn how PearData monitors hosts over peer-to-peer HyperDHT. Identity, hole punching, live metrics, alerts, QVAC, and security." />
|
||
<meta name="twitter:image" content="https://peardata.rest/assets/brand/twitter-card.png" />
|
||
<meta name="twitter:image:alt" content="PearData: decentralized P2P monitoring" />
|
||
|
||
<link rel="icon" href="/assets/favicons/favicon.ico" sizes="any" />
|
||
<link rel="icon" type="image/png" sizes="32x32" href="/assets/favicons/favicon-32x32.png" />
|
||
<link rel="icon" type="image/png" sizes="16x16" href="/assets/favicons/favicon-16x16.png" />
|
||
<link rel="icon" type="image/png" sizes="48x48" href="/assets/favicons/favicon-48x48.png" />
|
||
<link rel="apple-touch-icon" sizes="180x180" href="/assets/favicons/apple-touch-icon.png" />
|
||
<link rel="manifest" href="/assets/favicons/site.webmanifest" />
|
||
<link rel="mask-icon" href="/assets/logo/peardata-wordmark.svg" color="#34d399" />
|
||
|
||
<meta property="article:section" content="Learn" />
|
||
<meta property="article:author" content="HoneyPeer, LLC" />
|
||
<meta property="article:publisher" content="HoneyPeer, LLC" />
|
||
|
||
<script type="application/ld+json">
|
||
{
|
||
"@context": "https://schema.org",
|
||
"@type": "WebPage",
|
||
"name": "How PearData Works · P2P fleet monitoring",
|
||
"description": "Learn how PearData monitors hosts over peer-to-peer HyperDHT.",
|
||
"url": "https://peardata.rest/learn/",
|
||
"isPartOf": { "@type": "WebSite", "name": "PearData", "url": "https://peardata.rest" },
|
||
"publisher": { "@type": "Organization", "name": "HoneyPeer, LLC", "url": "https://peardata.rest" },
|
||
"inLanguage": "en-US"
|
||
}
|
||
</script>
|
||
|
||
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
||
<link href="https://fonts.googleapis.com/css2?family=Outfit:wght@400;500;600;700;800&family=IBM+Plex+Mono:wght@400;500&family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
|
||
<link rel="stylesheet" href="/src/styles/global.css" />
|
||
<link rel="stylesheet" href="/src/styles/docs.css" />
|
||
<link rel="stylesheet" href="/src/styles/learn.css" />
|
||
<link rel="stylesheet" href="/src/styles/theme-light.css" />
|
||
</head>
|
||
<body>
|
||
<div class="bg-mesh" aria-hidden="true"></div>
|
||
<div data-nav data-prefix="../"></div>
|
||
|
||
<header class="learn-hero">
|
||
<div class="learn-hero-inner">
|
||
<div class="badge mb-4">learn · how it works</div>
|
||
<h1>Peer-to-peer fleet monitoring</h1>
|
||
<p class="lead">
|
||
PearData is decentralized, real-time host observability on the Holepunch stack.
|
||
<strong>You never need to open ports or run a central SaaS control plane.</strong>
|
||
You only need keys, peers, and an agent on each machine.
|
||
</p>
|
||
<div class="learn-key">
|
||
<div>
|
||
<strong>Key concept</strong>
|
||
Your desktop and a remote agent talk directly over a Noise-encrypted HyperDHT stream.
|
||
No inbound firewall rules. No public metrics API. Discovery uses the DHT.
|
||
Live samples ride protomux-rpc pushes on that stream.
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</header>
|
||
|
||
<div class="container learn-page">
|
||
<ul class="learn-toc">
|
||
<li><a href="#why">Why P2P</a></li>
|
||
<li><a href="#problem">Old model</a></li>
|
||
<li><a href="#identity">Identity</a></li>
|
||
<li><a href="#connect">Connect</a></li>
|
||
<li><a href="#metrics">Metrics plane</a></li>
|
||
<li><a href="#desktop">Desktop</a></li>
|
||
<li><a href="#security">Security</a></li>
|
||
<li><a href="#qvac">QVAC</a></li>
|
||
</ul>
|
||
|
||
<section class="learn-section" id="why">
|
||
<h2>Why peer-to-peer for monitoring?</h2>
|
||
<p class="learn-lead">
|
||
Observability data is sensitive and hosts are everywhere. PearData keeps control and samples on your machines,
|
||
while still feeling like a modern multi-host console.
|
||
</p>
|
||
<ul>
|
||
<li><strong>No inbound ports</strong> for remote ops — dial by public key</li>
|
||
<li><strong>No central broker</strong> that sees your metrics</li>
|
||
<li><strong>Same product surface</strong> for one laptop or a fleet of agents</li>
|
||
</ul>
|
||
</section>
|
||
|
||
<section class="learn-section" id="problem">
|
||
<h2>The traditional remote-monitoring model</h2>
|
||
<p class="learn-lead">Most remote setups trade convenience for attack surface or a permanent middleman.</p>
|
||
<div class="learn-compare">
|
||
<div class="learn-card learn-card--old">
|
||
<h3>Common pain</h3>
|
||
<ul>
|
||
<li>Expose Prometheus / agent HTTP to the internet</li>
|
||
<li>Always-on VPN just to see dashboards</li>
|
||
<li>SaaS tenancy holding your fleet graph</li>
|
||
</ul>
|
||
</div>
|
||
<div class="learn-card learn-card--new">
|
||
<h3>PearData</h3>
|
||
<ul>
|
||
<li>Never open inbound ports for control traffic</li>
|
||
<li>Identity is a keypair, not a DNS name</li>
|
||
<li>You keep metrics and state on your hosts</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<pre class="mermaid">
|
||
flowchart LR
|
||
subgraph classic [Typical remote metrics]
|
||
VPN[VPN or public scrape] --> Prom[Prometheus / agent HTTP]
|
||
end
|
||
subgraph pd [PearData]
|
||
UI[Desktop client] -->|HyperDHT Noise| AG[Agent on host]
|
||
AG --> Mem[Hot rings]
|
||
AG --> HD[HyperDB warm]
|
||
end
|
||
</pre>
|
||
</section>
|
||
|
||
<section class="learn-section" id="identity">
|
||
<h2>Identity is a keypair</h2>
|
||
<p class="learn-lead">
|
||
Each agent generates an Ed25519 identity on first boot. The <strong>public key</strong> is safe to share for viewer access.
|
||
The <strong>seed</strong> is admin-only. Operators receive capability invites (<code>pd1.</code>) without the seed.
|
||
</p>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead>
|
||
<tr><th>Credential</th><th>Role</th><th>Use</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td><code>SERVER_PUBLIC_KEY</code></td><td>viewer</td><td>Read charts, alerts, health, subscribe</td></tr>
|
||
<tr><td><code>pd1.</code> invite</td><td>operator / admin</td><td>Minted by admin; no seed shared</td></tr>
|
||
<tr><td><code>SERVER_SEED</code></td><td>admin</td><td>Full control; protect like a root secret</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="learn-section" id="connect">
|
||
<h2>How a desktop connects</h2>
|
||
<p class="learn-lead">
|
||
The client dials the agent public key. HyperDHT finds a path; Noise encrypts the stream; protomux-rpc carries methods and pushes.
|
||
</p>
|
||
<div class="learn-peers">
|
||
<div class="learn-peer">
|
||
<strong>Desktop</strong>
|
||
<p>Electron / Pear UI</p>
|
||
</div>
|
||
<div class="learn-arrow"><span>⇄</span>lookup</div>
|
||
<div class="learn-peer learn-peer--hub">
|
||
<strong>HyperDHT</strong>
|
||
<p>Discovery + punch</p>
|
||
</div>
|
||
<div class="learn-arrow"><span>⇄</span>stream</div>
|
||
<div class="learn-peer">
|
||
<strong>Agent</strong>
|
||
<p>collect · store · RPC</p>
|
||
</div>
|
||
</div>
|
||
<div class="learn-steps">
|
||
<div class="learn-step">
|
||
<span class="learn-step-num">1</span>
|
||
<p>Install agent; read keys from <code>/opt/peardata/.env</code></p>
|
||
</div>
|
||
<div class="learn-step">
|
||
<span class="learn-step-num">2</span>
|
||
<p>Paste public key (or invite) into Connect</p>
|
||
</div>
|
||
<div class="learn-step">
|
||
<span class="learn-step-num">3</span>
|
||
<p>Subscribe to metrics; live charts fill in</p>
|
||
</div>
|
||
</div>
|
||
<pre class="mermaid">
|
||
sequenceDiagram
|
||
participant C as Desktop
|
||
participant D as HyperDHT
|
||
participant A as Agent
|
||
C->>D: lookup agent public key
|
||
D-->>C: peer address candidates
|
||
C->>A: Noise handshake
|
||
C->>A: handshake RPC
|
||
A-->>C: role + catalog
|
||
C->>A: subscribeMetrics *
|
||
A-->>C: push:metrics 1s
|
||
</pre>
|
||
</section>
|
||
|
||
<section class="learn-section" id="metrics">
|
||
<h2>Metrics plane</h2>
|
||
<p class="learn-lead">
|
||
About once per second the agent collects host samples into memory rings, evaluates anomaly thresholds,
|
||
and pushes to subscribed peers. Longer windows fall back to HyperDB warm storage.
|
||
</p>
|
||
<div class="learn-stack">
|
||
<div class="learn-layer">
|
||
<div class="learn-layer-name">Desktop</div>
|
||
<p>Overview KPIs, Charts wall, dashboards, alerts, QVAC tools</p>
|
||
</div>
|
||
<div class="learn-layer">
|
||
<div class="learn-layer-name">protomux-rpc</div>
|
||
<p>queryData, listCharts, listAlerts, AI composites, Data Manager</p>
|
||
</div>
|
||
<div class="learn-layer">
|
||
<div class="learn-layer-name">HyperDHT</div>
|
||
<p>Noise-encrypted secret stream · no public listen port for control</p>
|
||
</div>
|
||
<div class="learn-layer">
|
||
<div class="learn-layer-name">Agent pipeline</div>
|
||
<p>collector → store → anomaly → push · optional HyperDB flush</p>
|
||
</div>
|
||
<div class="learn-layer">
|
||
<div class="learn-layer-name">Host</div>
|
||
<p>/proc collectors · optional Docker/cgroup charts when enabled</p>
|
||
</div>
|
||
</div>
|
||
<pre class="mermaid">
|
||
flowchart TB
|
||
COL[Collector 1s] --> STORE[Hot / warm memory]
|
||
COL --> ANO[Anomaly engine]
|
||
STORE --> PUSH[push:metrics]
|
||
ANO --> APUSH[push:anomaly]
|
||
STORE --> HD[HyperDB warm]
|
||
PUSH --> UI[Desktop clients]
|
||
APUSH --> UI
|
||
</pre>
|
||
</section>
|
||
|
||
<section class="learn-section" id="desktop">
|
||
<h2>Desktop surfaces</h2>
|
||
<p class="learn-lead">One Electron / Pear shell for the whole fleet.</p>
|
||
<div class="table-wrap">
|
||
<table>
|
||
<thead>
|
||
<tr><th>View</th><th>Purpose</th></tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td>Overview</td><td>Live KPIs and sparks for the active agent</td></tr>
|
||
<tr><td>Charts</td><td>Full metrics wall, time bar, correlations</td></tr>
|
||
<tr><td>Dashboard</td><td>Custom boards (user + QVAC editable)</td></tr>
|
||
<tr><td>Alerts</td><td>Open thresholds + recent anomaly events</td></tr>
|
||
<tr><td>QVAC</td><td>On-device AI with tool calling into the agent</td></tr>
|
||
<tr><td>Logs / Processes / Fleet</td><td>Investigate and multi-host control</td></tr>
|
||
</tbody>
|
||
</table>
|
||
</div>
|
||
</section>
|
||
|
||
<section class="learn-section" id="security">
|
||
<h2>Security model</h2>
|
||
<p class="learn-lead">Default is least privilege. Transport is encrypted. Secrets stay local.</p>
|
||
<ul>
|
||
<li><strong>viewer</strong> by public key alone — read metrics and alerts</li>
|
||
<li><strong>operator</strong> via invite — silence/ack, run jobs (with confirm)</li>
|
||
<li><strong>admin</strong> via seed or admin keys — invites, retention, peer policy</li>
|
||
<li>Local REST on <code>127.0.0.1:18888</code> only — do not publish it</li>
|
||
<li>Desktop destructive actions use an in-app confirmation modal</li>
|
||
</ul>
|
||
<p>See the full <a href="/docs/security">security guide</a> and <a href="/legal/security">security policy</a>.</p>
|
||
</section>
|
||
|
||
<section class="learn-section" id="qvac">
|
||
<h2>QVAC (local AI)</h2>
|
||
<p class="learn-lead">
|
||
Inference runs on the desktop. Tools call the same agent RPCs you already use.
|
||
Broad “what’s wrong” questions can spawn a multi-agent swarm <em>inside the chat turn</em>, then collapse.
|
||
Stop cancels mid-run and unlocks the composer.
|
||
</p>
|
||
<ul>
|
||
<li>No cloud LLM API key required for the default design</li>
|
||
<li>Tools-only mode works without downloading a model</li>
|
||
<li>Auto-navigate: off / ask / on for tab switches</li>
|
||
</ul>
|
||
</section>
|
||
|
||
<div class="learn-cta">
|
||
<h2>Ready to try it?</h2>
|
||
<p>Install an agent, paste the public key into the client, and watch live metrics without a central control plane.</p>
|
||
<div class="learn-cta-actions">
|
||
<a class="btn btn-primary" href="/download">Install PearData</a>
|
||
<a class="btn btn-secondary" href="/docs/architecture">Architecture docs</a>
|
||
<a class="btn btn-ghost" href="/docs/">All documentation</a>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div data-footer data-prefix="../"></div>
|
||
<script type="module" src="/src/js/site.js"></script>
|
||
</body>
|
||
</html>
|