FAQ

Short answers to common questions.

Do I need to open ports or set up VPN / remote access?

No. PearDock is peer-to-peer over HyperDHT. You share the server’s public key; clients holepunch an encrypted connection. You do not open inbound firewall ports for Docker or the control UI, expose dockerd to the internet, or maintain a permanent VPN just to run ops. Optional Holesail tunnels reach published services the same way, still without punching host firewall holes.

How do I install PearDock?

curl -fsSL https://install.peardock.boats | bash

Interactive: choose server (Linux systemd) or client (desktop). Non-interactive: --server --yes / --client --yes. Details: Download & install.

What do I share with clients?

The server public key (64 hex characters). Never share SERVER_SEED.

Where is the public key after install?

sudo journalctl -u peardock -n 80 --no-pager | grep -i 'public key'

Also stored under /opt/peardock/.env as SERVER_PUBLIC_KEY when generated.

Container list empty / “permission denied” on Docker

The service user peardock needs the docker group:

sudo usermod -aG docker peardock
sudo systemctl restart peardock
# if the group was just created:
sudo systemctl restart docker

The one-line installer does this automatically on server install.

Is there a cloud / SaaS component?

No. HyperDHT holepunches between peers. Bootstrap nodes are part of the HyperDHT network; PearDock does not operate a proprietary control plane.

Pear prints “DEPRECATED: pear run is deprecated”

Platform-wide message. Prefer the Electron desktop client from the rolling release or install.sh --client. Source: npm run start:client.

macOS says the app is damaged

Usually quarantine or signature after download. Installer runs xattr -cr. Manually:

xattr -cr ~/Applications/peardock.app
# or right-click → Open
# re-sign from source build:
npm run sign:macos -- out/peardock-darwin-arm64/peardock.app

Client lost connection. Does it reconnect?

Yes. Unexpected disconnects retry every 5 seconds until the peer is back or you remove it. Last active peer is restored on launch.

Why is PearDock AGPL?

PearDock is AGPL-3.0, matching Holesail (also AGPL-3.0). If you modify PearDock and let others use it over a network, review AGPL source-offer obligations. You can set ENABLE_HOLESAIL=0 to disable tunnel creation.

Can I run without Holesail?

Yes: ENABLE_HOLESAIL=0 in the server environment. Control-plane Docker management still works.

Default role is admin. Is that safe?

Convenient for a single trusted operator. For multi-operator fleets, set PEARDOCK_DEFAULT_ROLE, PEARDOCK_ADMIN_KEYS, and allowlist. See threat model.

v1 vs v2

v1 used Hyperswarm topics and raw JSON streams. v2 uses HyperDHT keypairs, public keys, and protomux-rpc. Clients and servers are not wire-compatible across major versions.

Where is peer state stored on the client?

Typically ~/.config/peardock/cache/peers.json (includes last active peer id).

How do I update?

• Server: re-run install.sh --server --yes or replace the binary; keep /opt/peardock/.env; systemctl restart peardock.
• Client: re-run install.sh --client --yes or install a newer rolling tarball.
• Assets: rolling tag on every main CI build.

License

PearDock and Holesail: AGPL-3.0. See Open Source Notices.