238 lines
10 KiB
HTML
238 lines
10 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
|
|
<title>RPC & API · PearDock Docs</title>
|
|
<meta name="description" content="PearDock RPC method groups, server pushes, roles, and protocol version." />
|
|
<meta name="keywords" content="PearDock RPC, API, protomux-rpc, methods" />
|
|
<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="#2dd4bf" />
|
|
<meta name="color-scheme" content="dark light" />
|
|
<meta name="application-name" content="PearDock" />
|
|
<meta name="apple-mobile-web-app-title" content="PearDock" />
|
|
<meta name="apple-mobile-web-app-capable" content="yes" />
|
|
<meta name="mobile-web-app-capable" content="yes" />
|
|
<meta name="msapplication-TileColor" content="#2dd4bf" />
|
|
<meta name="msapplication-config" content="/assets/favicons/browserconfig.xml" />
|
|
<meta name="format-detection" content="telephone=no" />
|
|
<link rel="canonical" href="https://peardock.boats/docs/api" />
|
|
<link rel="alternate" hreflang="en" href="https://peardock.boats/docs/api" />
|
|
<link rel="alternate" hreflang="x-default" href="https://peardock.boats/docs/api" />
|
|
|
|
<!-- Open Graph -->
|
|
<meta property="og:type" content="article" />
|
|
<meta property="og:site_name" content="PearDock" />
|
|
<meta property="og:locale" content="en_US" />
|
|
<meta property="og:url" content="https://peardock.boats/docs/api" />
|
|
<meta property="og:title" content="RPC & API · PearDock Docs" />
|
|
<meta property="og:description" content="PearDock RPC method groups, server pushes, roles, and protocol version." />
|
|
<meta property="og:image" content="https://peardock.boats/assets/brand/og-image.png" />
|
|
<meta property="og:image:secure_url" content="https://peardock.boats/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="PearDock: decentralized Docker management on HyperDHT" />
|
|
|
|
<!-- Twitter / X -->
|
|
<meta name="twitter:card" content="summary_large_image" />
|
|
<meta name="twitter:title" content="RPC & API · PearDock Docs" />
|
|
<meta name="twitter:description" content="PearDock RPC method groups, server pushes, roles, and protocol version." />
|
|
<meta name="twitter:image" content="https://peardock.boats/assets/brand/twitter-card.png" />
|
|
<meta name="twitter:image:alt" content="PearDock: decentralized Docker management" />
|
|
|
|
<!-- Icons & PWA -->
|
|
<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/peardock-wordmark.svg" color="#2dd4bf" />
|
|
|
|
<!-- Article -->
|
|
<meta property="article:section" content="Documentation" />
|
|
<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",
|
|
"TechArticle"
|
|
],
|
|
"name": "RPC & API \u00b7 PearDock Docs",
|
|
"description": "PearDock RPC method groups, server pushes, roles, and protocol version.",
|
|
"url": "https://peardock.boats/docs/api",
|
|
"isPartOf": {
|
|
"@type": "WebSite",
|
|
"name": "PearDock",
|
|
"url": "https://peardock.boats"
|
|
},
|
|
"publisher": {
|
|
"@type": "Organization",
|
|
"name": "HoneyPeer, LLC",
|
|
"url": "https://peardock.boats"
|
|
},
|
|
"inLanguage": "en-US",
|
|
"primaryImageOfPage": {
|
|
"@type": "ImageObject",
|
|
"url": "https://peardock.boats/assets/brand/og-image.png",
|
|
"width": 1200,
|
|
"height": 630
|
|
},
|
|
"headline": "RPC & API \u00b7 PearDock Docs"
|
|
}
|
|
</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=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
|
|
<link rel="stylesheet" href="/src/styles/global.css" />
|
|
<link rel="stylesheet" href="/src/styles/docs.css" />
|
|
</head>
|
|
<body>
|
|
<div class="bg-mesh" aria-hidden="true"></div>
|
|
<div data-nav data-prefix="../"></div>
|
|
|
|
<div class="docs-layout">
|
|
<aside class="docs-sidebar" data-docs-nav data-prefix="../"></aside>
|
|
<button type="button" class="docs-sidebar-toggle" aria-label="Docs menu">☰</button>
|
|
|
|
<article class="docs-main">
|
|
<h1>RPC & API reference</h1>
|
|
<p class="docs-lead">
|
|
PearDock speaks <strong>protomux-rpc</strong> over HyperDHT. Methods and push channels are defined in
|
|
<code>shared/protocol.js</code>. This page summarizes groups for operators and integrators.
|
|
</p>
|
|
|
|
<div class="callout info">
|
|
<div class="callout-icon">i</div>
|
|
<div class="callout-body">
|
|
There is no public HTTP API. The only control surface is the P2P RPC session after
|
|
Noise handshake. Typed helpers live in <code>client/api.js</code>.
|
|
</div>
|
|
</div>
|
|
|
|
<h2>Handshake</h2>
|
|
<p>On connect, the client calls <code>handshake</code>. The server returns:</p>
|
|
<ul>
|
|
<li>Negotiated <code>PROTOCOL_VERSION</code></li>
|
|
<li><code>peerId</code> for this connection</li>
|
|
<li>Role (viewer / operator / admin)</li>
|
|
<li>Feature flags (swarm, plugins, holesail, …)</li>
|
|
</ul>
|
|
|
|
<h2>Roles</h2>
|
|
<div class="table-wrap">
|
|
<table>
|
|
<thead>
|
|
<tr><th>Role</th><th>Typical access</th></tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><code>viewer</code></td><td>List/read, stats, logs (read), tunnel list</td></tr>
|
|
<tr><td><code>operator</code></td><td>Start/stop, deploy, tunnels, most mutations</td></tr>
|
|
<tr><td><code>admin</code></td><td>Peers, vault, unrestricted CLI (if enabled), ACL</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<p>Exact method→role map is in server ACL (<code>server/core/acl.js</code> / <code>MethodRoles</code>).</p>
|
|
|
|
<h2>Method groups (client → server)</h2>
|
|
|
|
<h3>Session & system</h3>
|
|
<ul>
|
|
<li><code>handshake</code>, <code>ping</code></li>
|
|
<li><code>getSystemDf</code>, <code>getMetrics</code>, <code>systemPrune</code></li>
|
|
<li>Host suggestions / snapshot helpers</li>
|
|
</ul>
|
|
|
|
<h3>Containers</h3>
|
|
<ul>
|
|
<li><code>listContainers</code>, inspect, start, stop, kill, restart, remove</li>
|
|
<li><code>deployContainer</code>, <code>recreateContainer</code>, <code>updateContainer</code> (resources)</li>
|
|
<li><code>containerTop</code>, archive, rename, network connect/disconnect</li>
|
|
<li><code>startTerminal</code> / terminal I/O channels</li>
|
|
<li><code>getContainerLogs</code> (+ download/export in UI)</li>
|
|
</ul>
|
|
|
|
<h3>Images, volumes, networks</h3>
|
|
<ul>
|
|
<li>List / pull / remove / prune images; Hub search</li>
|
|
<li>Volume list/create/remove; <code>browseVolume</code></li>
|
|
<li>Network list/create/remove/connect/disconnect</li>
|
|
</ul>
|
|
|
|
<h3>Stacks & GitOps</h3>
|
|
<ul>
|
|
<li><code>deployStack</code> with compose content, override, env file, profiles, build flag</li>
|
|
<li>GitOps helpers for remote compose sources</li>
|
|
</ul>
|
|
|
|
<h3>Swarm (feature-gated)</h3>
|
|
<ul>
|
|
<li>Services, nodes, tasks</li>
|
|
<li>Secrets / configs create + list</li>
|
|
<li><code>scaleService</code></li>
|
|
</ul>
|
|
|
|
<h3>Peers, vault, access</h3>
|
|
<ul>
|
|
<li>Peer list / register / revoke / invites</li>
|
|
<li><code>vaultStoreCredential</code>, <code>vaultUseCredential</code>, list vault entries</li>
|
|
</ul>
|
|
|
|
<h3>Holesail tunnels</h3>
|
|
<ul>
|
|
<li><code>getHolesailStatus</code>, <code>listTunnels</code>, <code>getTunnel</code></li>
|
|
<li><code>createTunnel</code>, <code>closeTunnel</code></li>
|
|
</ul>
|
|
|
|
<h3>Schedules</h3>
|
|
<ul>
|
|
<li>List / create / delete maintenance schedules (prune, ping, …)</li>
|
|
</ul>
|
|
|
|
<h2>Pushes (server → client)</h2>
|
|
<div class="table-wrap">
|
|
<table>
|
|
<thead>
|
|
<tr><th>Channel</th><th>Payload (conceptually)</th></tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr><td><code>push:containers</code></td><td>Container list deltas / refresh</td></tr>
|
|
<tr><td><code>push:allStats</code></td><td>Live CPU/mem/net stats</td></tr>
|
|
<tr><td><code>push:logs</code></td><td>Log lines for open streams</td></tr>
|
|
<tr><td><code>push:pullProgress</code></td><td>Image pull layers</td></tr>
|
|
<tr><td><code>push:buildProgress</code></td><td>Build / compose build output</td></tr>
|
|
<tr><td><code>push:dockerEvent</code></td><td>Engine events</td></tr>
|
|
<tr><td><code>push:terminalOutput</code></td><td>PTY bytes for exec sessions</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<h2>Integrating programmatically</h2>
|
|
<p>Use the same stack as the desktop client:</p>
|
|
<ol>
|
|
<li>Open a HyperDHT connection to the server public key.</li>
|
|
<li>Attach protomux + protomux-rpc.</li>
|
|
<li>Call <code>handshake</code>, then domain methods.</li>
|
|
<li>Subscribe to push channels as needed.</li>
|
|
</ol>
|
|
<p>Reference implementations: <code>client/connection.js</code>, <code>client/api.js</code>, <code>client/manager.js</code>.</p>
|
|
|
|
<div class="docs-pager">
|
|
<a href="/docs/security"><span>Previous</span><strong>← Security</strong></a>
|
|
<a class="next" href="/docs/release"><span>Next</span><strong>Releases →</strong></a>
|
|
</div>
|
|
</article>
|
|
</div>
|
|
|
|
<div data-footer data-prefix="../"></div>
|
|
<script type="module" src="/src/js/site.js"></script>
|
|
</body>
|
|
</html>
|