VaultPeer Server Node

The headless sync node for VaultPeer — an open-source, privacy-first KeePass-compatible password manager with live multi-device sync over WebRTC.

---

Table of Contents

• Introduction
• Features
• Installation
• Configuration
• Usage
• Docker
• Dependencies
• Related Projects
• Contributing
• License

---

Introduction

VaultPeer is an open-source, privacy-first password manager that gives you full control over your credentials. It stores vaults in the standard KDBX format used by KeePass and KeePassXC, encrypts everything at rest, and keeps your data on your devices.

Unlike cloud-first password managers, VaultPeer uses a Phonebook signaling server for peer discovery only. Every node — desktop, mobile, or this headless server node — joins a room on Phonebook, discovers other live nodes, and exchanges the encrypted .kdbx vault over WebRTC data channels. Phonebook relays connection metadata only; it never sees your decrypted vault contents.

VaultPeer Server Node is the always-on peer in that network. It has no UI — you cannot create, edit, or unlock entries through it. It holds the encrypted vault file on disk, syncs on startup and after changes with other nodes, and acts as a 24/7 backup peer that accepts incoming pushes and serves pulls to desktop and mobile nodes.

Note: The server node is not the signaling server. Only VaultPeer-Phonebook handles signaling. The server node is a peer, like desktop and mobile, but headless.

---

Features

• KeePass-compatible storage — Holds standard .kdbx databases; the vault remains encrypted at rest with your master password.
• Live multi-device sync — Connects to VaultPeer-Phonebook, joins a room, and syncs with desktop, mobile, and other server nodes over WebRTC.
• Headless operation — No graphical interface; designed for VPS, NAS, or home-server deployment.
• Always-on backup — Keeps a copy of the vault and participates in push/pull sync so other nodes can recover the latest revision.
• Automatic revision backups — Retains the last N overwritten revisions on disk (configurable via BACKUP_RETENTION).
• Docker-ready — Multi-stage Alpine image with a non-root runtime user.
• No telemetry — No analytics or cloud vault; outbound traffic is limited to Phonebook and WebRTC/STUN/TURN.

---

Installation

Prerequisites

• Node.js 22+ — check .nvmrc and verify with:

node --version

• A running VaultPeer-Phonebook instance reachable from this host.
• At least one other VaultPeer node (desktop or mobile) that has already created or synced the vault, or a pre-placed .kdbx file in the storage directory.

Steps

# 1. Clone the repository
git clone https://github.com/mHamzaIqbal1998/VaultPeer-ServerNode.git

# 2. Go to the cloned directory
cd VaultPeer-ServerNode

# 3. Install dependencies
npm ci

# 4. Configure environment (see Configuration below)
cp .env.example .env
# Edit .env — at minimum set VAULT_ID and SIGNALING_URL

# 5. Start the node
npm start

For local development with auto-reload:

npm run dev

---

Configuration

All settings are read from environment variables at startup.

Variable	Required	Default	Description
VAULT_ID	Yes	—	Room ID shared by all nodes syncing the same vault.
SIGNALING_URL	No	ws://localhost:8080	WebSocket URL of your Phonebook server.
STORAGE_DIR	No	/data	Directory for the encrypted .kdbx file.
KDBX_FILENAME	No	vault.kdbx	Vault filename (must match other nodes).
LOG_LEVEL	No	info	debug, info, warn, or error.
ICE_SERVERS	No	(Google STUN)	JSON array of STUN/TURN servers for NAT traversal.
BACKUP_RETENTION	No	5	Previous revisions to keep on overwrite (0 disables).

See .env.example for a full template.

---

Usage

1. Deploy and start VaultPeer-Phonebook.
2. Configure this server node with the same VAULT_ID and KDBX_FILENAME as your desktop or mobile node.
3. Start the server node. On connect it joins the room and exchanges metadata with peers.
4. If the server has no vault yet, a newer copy is pulled from a connected peer automatically.
5. When a desktop or mobile node saves changes, the server node receives a push and stores the updated file. Conversely, if another peer is newer, the server pulls the latest revision.

The server node never decrypts the vault — it only stores and transfers the encrypted KDBX bytes.

---

Docker

# Create a named volume for persistent vault storage (once)
docker volume create VaultPeer

# Copy and edit environment variables
cp .env.example .env

# Build and run
docker compose up -d --build

Logs:

docker compose logs -f vaultpeer-node

The container exposes no inbound ports. All communication is outbound (WebSocket to Phonebook, WebRTC via STUN/TURN).

---

Dependencies

• Node.js 22+
• node-datachannel — WebRTC peer connections
• ws — WebSocket client for Phonebook
• chokidar — filesystem watcher for local vault changes

---

Related Projects

Project	Description
VaultPeer-Desktop	Windows desktop node with UI
VaultPeer-Mobile	Mobile node with UI
VaultPeer-ServerNode	Headless sync node — no UI; holds the vault and relays push/pull to other nodes (this repository)
VaultPeer-Phonebook	WebRTC signaling server for room join and peer discovery

All nodes share the same sync protocol and KDBX vault format. Only Phonebook handles signaling; every other component is a peer node.

---

Contributing

We welcome contributions. See CONTRIBUTING.md for the development workflow and coding conventions.

---

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.