RPC & API reference

PearDock speaks protomux-rpc over HyperDHT. Methods and push channels are defined in shared/protocol.js. This page summarizes groups for operators and integrators.

There is no public HTTP API. The only control surface is the P2P RPC session after Noise handshake. Typed helpers live in client/api.js.

Handshake

On connect, the client calls handshake. The server returns:

Negotiated PROTOCOL_VERSION
peerId for this connection
Role (viewer / operator / admin)
Feature flags (swarm, plugins, holesail, …)

Roles

Role	Typical access
`viewer`	List/read, stats, logs (read), tunnel list
`operator`	Start/stop, deploy, tunnels, most mutations
`admin`	Peers, vault, unrestricted CLI (if enabled), ACL

Exact method→role map is in server ACL (server/core/acl.js / MethodRoles).

Method groups (client → server)

Session & system

handshake, ping
getSystemDf, getMetrics, systemPrune
Host suggestions / snapshot helpers

Containers

listContainers, inspect, start, stop, kill, restart, remove
deployContainer, recreateContainer, updateContainer (resources)
containerTop, archive, rename, network connect/disconnect
startTerminal / terminal I/O channels
getContainerLogs (+ download/export in UI)

Images, volumes, networks

List / pull / remove / prune images; Hub search
Volume list/create/remove; browseVolume
Network list/create/remove/connect/disconnect

Stacks & GitOps

deployStack with compose content, override, env file, profiles, build flag
GitOps helpers for remote compose sources

Swarm (feature-gated)

Services, nodes, tasks
Secrets / configs create + list
scaleService

Peers, vault, access

Peer list / register / revoke / invites
vaultStoreCredential, vaultUseCredential, list vault entries

Holesail tunnels

getHolesailStatus, listTunnels, getTunnel
createTunnel, closeTunnel

Schedules

List / create / delete maintenance schedules (prune, ping, …)

Pushes (server → client)

Channel	Payload (conceptually)
`push:containers`	Container list deltas / refresh
`push:allStats`	Live CPU/mem/net stats
`push:logs`	Log lines for open streams
`push:pullProgress`	Image pull layers
`push:buildProgress`	Build / compose build output
`push:dockerEvent`	Engine events
`push:terminalOutput`	PTY bytes for exec sessions

Integrating programmatically

Use the same stack as the desktop client:

Open a HyperDHT connection to the server public key.
Attach protomux + protomux-rpc.
Call handshake, then domain methods.
Subscribe to push channels as needed.

Reference implementations: client/connection.js, client/api.js, client/manager.js.