Holesail tunnels

Holesail is a peer-to-peer TCP/UDP reverse proxy on HyperDHT. PearDock uses it beside the Docker control plane so you can share published services via hs:// keys. No open ports, no inbound firewall rules, no “expose this to the internet” step.

Do not conflate the two planes

flowchart LR
  subgraph Control["Control plane"]
    CLI[Client RPC]
    SRV[Server handlers]
    CLI -- "protomux-rpc" --> SRV
    SRV --> DK[Docker]
  end
  subgraph Data["Data plane"]
    HS[HolesailServer]
    HC[Holesail client]
    HC -- "hs:// P2P" --> HS
    HS --> PT["host:port"]
  end
  Control -.->|"orthogonal · not a replacement"| Data

Plane	Technology	Purpose
Control	HyperDHT + protomux-rpc	Docker RPC, ACL, logs, deploy
Data / tunnels	Holesail	L4 proxy host:port ↔ remote peer

Enable / disable

Holesail tunnels are enabled by default. The holesail package is a required dependency.

# default: tunnels on
npm run server

# opt out
export ENABLE_HOLESAIL=0
npm run server

Variable	Default	Meaning
`ENABLE_HOLESAIL`	on	Set 0 / false / off / no to disable
`PEARDOCK_MAX_TUNNELS`	20	Concurrent tunnel cap
`PEARDOCK_TUNNEL_HOSTS`	loopback + 0.0.0.0	Allowed tunnel targets (SSRF guard)

RPC

Method	Role	Description
`getHolesailStatus`	viewer	Feature flag + availability
`listTunnels`	viewer	Active tunnels (+ hs:// URLs)
`getTunnel`	viewer	One tunnel by id
`createTunnel`	operator	Start tunnel (host/port or container + port)
`closeTunnel`	operator	Stop tunnel

createTunnel uses secure mode by default so the DHT capability is not the raw listen key.

UI

Sidebar → Tunnels: create by host/port, list active tunnels, copy hs:// URL, close.

Remote connect (outside PearDock):

npx holesail 'hs://s000…'
# then open http://127.0.0.1:<bound-port>

Security

Treat hs:// URLs as secrets (capability to reach the service).
Default targets are loopback / published Docker binds only.
Create/close are audited when PEARDOCK_AUDIT is on.
Max tunnel count limits resource exhaustion.
Do not reuse SERVER_SEED for tunnel keypairs. Each tunnel gets its own Holesail seed.

License note

holesail is a required dependency. PearDock and Holesail are both AGPL-3.0. Operators of modified network servers should review AGPL source-offer obligations. Set ENABLE_HOLESAIL=0 if you must run without opening tunnels (package still installed).