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?

Viewers: SERVER_PUBLIC_KEY only (64 hex). Read-only.
Admins: public key plus SERVER_SEED from the same .env. Never send the seed over chat to operators.
Operators: a full pd1.… invite from Access → Create invite (embeds key + capability; no seed).

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 or RocksDB. No seed sharing. Invites can be persistent (default) or limited by TTL or 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).

Where do I store registry credentials?

In the desktop app open the top-level Registry view (not Access). Vault credentials are encrypted on the server in peardock-vault.json (AES-GCM from SERVER_SEED). From Registry you can also search Docker Hub, browse remote catalogs/tags/manifests, and pull with a selected credential. Pull/push from the Images view can use the same vault entries.

Where did Peers go? Where are saved hosts?

Settings → Peers manages client-side saved hosts (public keys, aliases). Server-side ACL for invites, revoke, and roles stays under Access.

What does the Updates column on containers mean?

PearDock compares each container’s local image RepoDigest to the remote registry manifest for the same tag. Green = up to date, orange = update available (click to pull), grey = unknown/skipped. Check updates in the containers action bar forces a recheck and reports in the job tray. Private registries use vault credentials. Server caches digests for about five minutes. RPC: checkImageUpdates.

How do long image pulls show progress?

Pull and push stream layer events over push:pullProgress / push:pushProgress. The desktop job tray aggregates them into hybrid overall progress, phase labels, and a fixed-height layer track. Not a single misleading percentage.

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.