@toolkit-p2p/headless

Headless peer runtime for Lighthouse persistence layer

Version: 0.3.0

Overview

The headless package provides a daemon runtime for running Toolkit-P2P as an always-on peer without UI. This enables Lighthouse - a persistence layer that keeps P2P networks alive when all human participants go offline.

Features

• Daemon lifecycle management (start, stop, status)
• DID identity generation and persistence
• Trust ticket import/export
• Integration with all v0.2.0 packages (identity, sync, transport, mesh-cache)
• Store-and-forward messaging (mailbox)
• Shared state preservation (bulletin CRDT)
• TTL and relay depth enforcement

Installation

pnpm add @toolkit-p2p/headless

Usage

import { HeadlessNode } from '@toolkit-p2p/headless';

const lighthouse = new HeadlessNode({
  storagePath: '~/.lighthouse',
  port: 3000,
});

await lighthouse.start();

// Lighthouse is now running...

await lighthouse.stop();

Philosophy

Lighthouse is not a server. It's just another peer that never sleeps. It enforces the same trust tickets, hop limits (≤3), and TTL (≤48h) as all peers.

Deployment

Raspberry Pi Lighthouse

Deploy an always-on Lighthouse node on a Raspberry Pi for production P2P network continuity:

• Deployment Guide - Complete setup instructions
• Example Scripts - Ready-to-use deployment files

Quick start:

npm install -g @toolkit-p2p/headless level
mkdir -p ~/.lighthouse
# Copy example files and configure
node ~/.lighthouse/lighthouse.js

See the examples/raspberry-pi directory for systemd service templates and configuration examples.

Package Status

Version: 0.3.0 (in development) Status: Foundation phase (Week 1)

Dependencies

• @toolkit-p2p/identity - Ed25519 identity, DID, trust tickets
• @toolkit-p2p/sync - CRDTs, Vector Clocks, Merkle trees
• @toolkit-p2p/transport - WebRTC mesh networking
• @toolkit-p2p/mesh-cache - Content-addressed storage

License

MIT © 2025 Aaron Rosenthal