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?

Never share SERVER_SEED with operators.

Where are the public key and seed after install?

After the first successful start, both are written to /opt/peardock/.env. Check that file: 

sudo grep -E '^(SERVER_PUBLIC_KEY|SERVER_SEED)=' /opt/peardock/.env
# or: sudo cat /opt/peardock/.env

# Public key also appears in the journal
sudo journalctl -u peardock -n 80 --no-pager | grep -i 'public key'

SERVER_PUBLIC_KEY is safe to share for viewer access. SERVER_SEED is admin-only. Keep .env mode 600 and back it up offline.

How do invites work?

As admin (public key + SERVER_SEED in Add peer), open Access → Create invite and copy the full string starting with pd1.. The operator pastes that entire string in Add peer. Public key and HMAC capability are embedded — no Autopass/RocksDB and no seed sharing. Invites can be persistent (default) or limited by TTL / max uses. Revoke peers from Access when devices are lost. Deep dive: Security model.

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 viewer. How do I get admin?

Public key alone is viewer (read-only). For admin, paste SERVER_PUBLIC_KEY + SERVER_SEED from /opt/peardock/.env in Add peer. For multi-operator fleets, create pd1. invites instead of sharing the seed. Optional: PEARDOCK_ADMIN_KEYS, 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?

License

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

Previous← Releases