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 + 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/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).

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 — invites, revoke, 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.