Quick start

Fastest path: the one-line installer (rolling binaries). After install you connect with a public key. No ports to open, no VPN, no public Docker API. Alternative: run from source with Node.js ≥ 20.

1. One-line installer (recommended)

Detects OS/arch, downloads matching assets from the rolling release, and installs either a Linux systemd server or a desktop client. 

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

Non-interactive:

# Server on Linux (systemd → peardock.service)
curl -fsSL https://install.peardock.boats | bash -s -- --server --yes

# Desktop client (Linux or macOS)
curl -fsSL https://install.peardock.boats | bash -s -- --client --yes

# Both (Linux host that also runs the GUI)
curl -fsSL https://install.peardock.boats | bash -s -- --both --yes
i
Requirements. curl or wget, tar. Server install needs root/sudo, Docker installed, and Linux for systemd. Windows: grab tarballs from the rolling release (bash installer is not for win32).

2. After server install

Default layout:

PathPurpose
/opt/peardock/peardock-serverBare standalone binary
/opt/peardock/.envCheck this file for SERVER_PUBLIC_KEY and SERVER_SEED (mode 600)
/etc/systemd/system/peardock.servicesystemd unit (user peardock, group docker)
 
sudo systemctl enable --now peardock
sudo systemctl status peardock
sudo journalctl -u peardock -f

Keys live in .env

After the first successful start, the server writes identity into /opt/peardock/.env. Open that file (or grep it) before connecting: 

# Preferred — both keys after first start
sudo grep -E '^(SERVER_PUBLIC_KEY|SERVER_SEED)=' /opt/peardock/.env
# or: sudo cat /opt/peardock/.env

# Also printed in the journal on boot
sudo journalctl -u peardock -n 80 --no-pager | grep -i 'public key'
VariableWhoIn the client
SERVER_PUBLIC_KEY Safe to share Paste alone → viewer (read-only)
SERVER_SEED Admins only — never give to operators Paste with the public key → admin

Boot log shape:

  peardock server ready
  Public key (viewer / read-only by default):
  <64 hex characters>
  Admin: paste public key + SERVER_SEED in the client.
  Operators: create a pd1. invite from Access (never share SERVER_SEED).
!
Docker socket. The installer adds user peardock to the docker group so /var/run/docker.sock is usable. If list/start fails with permission errors: sudo usermod -aG docker peardock && sudo systemctl restart peardock. Back up SERVER_SEED in .env. Rotating it changes the public key.

3. After client install

Dev/source alternative (Electron):

npm run start:client
# builds electron/app.bundle.cjs then launches Electron

Pear development:

export PATH="$HOME/Library/Application Support/pear/bin:$PATH"   # macOS
npm run dev

4. Connect

flowchart LR
  A[Install server] --> B["Read keys from /opt/peardock/.env"]
  B --> C[Install / open client]
  C --> D[Add peer · key / seed / pd1 invite]
  D --> E[Handshake · role · live UI]
  1. On the Docker host, read keys from /opt/peardock/.env (SERVER_PUBLIC_KEY, and SERVER_SEED if you need admin).
  2. Open the client → Add peer.
  3. Paste one of the options below (optional alias).
  4. Handshake returns peerId and role; the live UI loads.
Paste in Add peerAccess
Public key only (SERVER_PUBLIC_KEY)Viewer (read-only)
Public key + SERVER_SEED (from the same .env)Admin
Full pd1.… invite (from Access → Create invite)Role in the invite — no seed sharing

Default peer role is viewer (public key alone). Elevate with seed proof or a pd1. invite. Multi-operator fleets: operator guide and threat model.

Saved peers reconnect automatically (retry every 5s if a peer drops). Last active peer is restored on client launch.

5. From source

git clone https://git.ssh.surf/snxraven/peardock.git
cd peardock
npm install          # or: npm ci
npm run server       # host with Docker
npm run start:client # Electron GUI
# npm run dev        # Pear desktop (dev)

Production server host from source:

npm ci --omit=dev
# copy deploy/peardock.service, create user peardock, add to docker group
# or use install.sh for the binary path instead

6. Standalone binaries (local make)

64-bit only: linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64, win32-arm64.

npm run make                    # all server + client hosts
npm run make:server:linux-x64
npm run make:client:darwin-arm64

Outputs under out/. CI publishes tag rolling. See Releases and Download.

Previous← Overview