Peer-to-peer Docker control

Why peer-to-peer for Docker?

Docker Engine is powerful locally. Remotely, people usually open a TLS API port, maintain a VPN, or enroll hosts in a hosted panel. PearDock takes another path: treat the host as a peer you reach with a public key. No open ports, no exposed Engine, no remote-access checklist that never ends.

You can manage a home lab behind CGNAT, a VPS without punching firewall holes, or a fleet of edge machines. Peers need to complete HyperDHT hole punching (or a relay fallback), and you need the right key material.

The traditional remote-Docker model

Most “remote Docker” setups trade convenience for a large attack surface or a permanent middleman.

flowchart LR
  subgraph Traditional["Traditional"]
    A1[Laptop] --> VPN[VPN / open :2376 / SaaS]
    VPN --> D1[dockerd]
  end
  subgraph PearDock["PearDock"]
    A2[Desktop client] -- "HyperDHT + Noise + protomux-rpc" --> S2[peardock-server]
    S2 --> D2[dockerd]
  end
      

Identity: seeds and public keys

PearDock v2 identity is a HyperDHT keypair derived from a secret seed. It is not a shared “topic string” like some older swarm designs.

On first start the server writes SERVER_SEED and SERVER_PUBLIC_KEY to /opt/peardock/.env (mode 600) and prints the public key in the journal. Check the .env file for both values before connecting. Rotating the seed changes the public key. All clients must re-add the peer. Back up that file like any other root secret.

How a client finds and connects to a server

Under the hood this is classic Holepunch connectivity: announce, look up, hole-punch (or relay), then encrypt. PearDock’s application layer starts only after that secure stream exists.

sequenceDiagram
  participant C as Client
  participant DHT as HyperDHT
  participant S as peardock-server
  participant D as dockerd
  S->>DHT: announce identity
  C->>DHT: lookup public key
  DHT-->>C: candidate endpoints
  C->>S: hole punch / connect
  C->>S: Noise handshake
  C->>S: protomux-rpc handshake
  S-->>C: role · protocol version
  C->>S: listContainers / deploy / …
  S->>D: dockerode
  D-->>S: result
  S-->>C: response + optional pushes
      

NAT traversal & hole punching

Most devices sit behind Network Address Translation. Routers map private IPs to public ports and block unsolicited inbound traffic. That is why “just open Docker on the internet” is a bad default, and why P2P needs help to dial home.

What hole punching does

1. Both peers learn public endpoints via DHT-assisted signaling (not a single app-specific rendezvous you host).
2. Simultaneous outbound probes create temporary NAT mappings toward each other.
3. Direct path preferred when mappings cooperate (common on home NAT).
4. Relay fallback may apply when both sides are hard symmetric NAT. Traffic stays encrypted. Relays do not get plaintext Docker commands.

PearDock benefits from the same Holepunch/libudx generation of tools that power Hyperswarm and Holesail. You don’t configure port forwards for the control channel. You share a key. That is the whole remote-access story: no open ports, no exposed Engine, no perpetual VPN.

Control plane: protomux-rpc over HyperDHT

Once the encrypted stream is up, PearDock speaks a structured RPC protocol, not ad-hoc JSON lines. That is how the UI stays rich: typed methods, roles, and live pushes.

Client → server (examples)

• handshake, ping: session setup and liveness
• listContainers, checkImageUpdates, start/stop, recreateContainer
• deployContainer, deployStack, syncStackFromGit
• getContainerLogs, startTerminal, containerStats
• Registry vault + catalog/tags/manifest, Swarm, schedules, tunnels

Server → client pushes

• push:containers, push:allStats: live fleet view without spam polling
• push:logs, push:terminalOutput: streaming operator surfaces
• push:pullProgress / push:pushProgress / build progress: hybrid job-tray layer progress when the Engine streams events

Method ↔ role maps live in the shared protocol. Viewers can observe; operators mutate day-to-day; admins get destructive and policy-level actions. See RPC & API and Security.

Data plane: Holesail tunnels (optional traffic path)

Managing Docker is not the same as reaching a published web app or TCP service. PearDock keeps a second plane for that: Holesail L4 tunnels. Still no open host ports. Share an hs:// key instead of a firewall rule.

flowchart LR
  subgraph Control["Control plane"]
    UI[Client RPC]
    SRV[Server handlers]
    UI --> SRV
    SRV --> DK[Docker Engine]
  end
  subgraph Data["Data plane"]
    HC[Holesail client]
    HS[HolesailServer]
    HC -- "hs:// capability" --> HS
    HS --> Port["host:published-port"]
  end
  Control -.->|"orthogonal"| Data
      

Why not use only Holesail? Holesail moves bytes between sockets. It is not an RPC framework, role system, or audit log. PearDock needs structured methods and live UI channels, so control stays on protomux-rpc.

Tunnels are on by default (ENABLE_HOLESAIL=0 to disable). Treat every hs:// URL as a capability secret. Details: Holesail guide.

Security model (operator mental model)

P2P does not mean “open to the world.” It means “reachable by those who hold the right cryptographic handles.”

• Transport encryption: Noise on the HyperDHT stream, not cleartext Docker API on :2375.
• Roles: viewer (default for public key alone), operator, and admin gate methods server-side.
• Keys in .env: after install, check /opt/peardock/.env for SERVER_PUBLIC_KEY and SERVER_SEED.
• Peer policy: optional allowlists, pd1. invites (no seed sharing), and revoke for multi-operator fleets.
• Rate limits and audit: blunt force protection and accountability for privileged calls.
• Registry vault + browser: credentials encrypted at rest (AES-GCM); remote catalog/tags/manifests via Registry HTTP API V2. UI: top-level Registry view.
• Tunnel SSRF guard: default allowlist for tunnel targets (loopback and published binds).
• Browse roots: host filesystem browse is default-deny and constrained.

You still must secure Docker itself: who is in the docker group, what images you run, and how secrets enter containers. PearDock is a control surface. It inherits the power of the Engine socket it uses.

Deep dive: Threat model & hardening · Vulnerability reporting

Multi-peer fleet UX

One desktop client can keep many servers. Each peer is a separate HyperDHT identity with its own role and health.

• Disk-backed peer cache under the client config directory
• Saved hosts edited under Settings → Peers; server ACL/invites under Access
• Auto-reconnect (retry every 5s when a peer drops)
• Environment tags (prod / staging / lab) for mental models
• Multi-step job tray with hybrid image pull/push progress for long ops
• Registry browser, image update checks, Portainer-style templates on the active peer

There is no “log into PearDock cloud.” There is only: which public keys did you add, and which of those peers are online.

End-to-end: first session

From zero to a live containers list. This is the path most operators take.

flowchart TB
  A[Install peardock-server on Docker host] --> B["Read keys from /opt/peardock/.env"]
  B --> C[Install desktop client]
  C --> D[Add peer · key / seed / pd1 invite]
  D --> E[Handshake · role · protocol version]
  E --> F[listContainers · stats pushes · manage]
  F --> G{Need app traffic?}
  G -->|Yes| H[Create Holesail tunnel · share hs://]
  G -->|No| I[Stay on control plane only]
      

1. Install the server (one-liner or binary) on a machine with Docker.
2. Read SERVER_PUBLIC_KEY and (for admin) SERVER_SEED from /opt/peardock/.env.
3. Install the client; Add peer with key / key+seed / full pd1. invite; wait for health.
4. Operate: containers (updates), registry, templates, stacks, logs, terminal, Swarm, prune…
5. Optionally tunnel a published port with Holesail for users outside the control path.

Install: Download & install · Guide: Quick start · Binaries: Releases

Glossary