Setting Up Personal Nodes

⚠️ POC Status: Experimental software demonstrating the Osvauld protocol. Security model and functionality still evolving.

Personal nodes are your always-on devices running the Osvauld protocol. Orange Pi 6 Plus provides affordable, capable hardware you control.

What Personal Nodes Do

Personal nodes use the Osvauld protocol to:

• Merge: Process CRDT operations for conflict-free merging
• Send resource updates: Push updates to other users when resources change
• Cache updates: Store updates from other users when they’re offline
• Distribute content: Handle all distribution between users
• Coordinate sync: Facilitate peer-to-peer connections

You need at least one personal node for flawless operation. The node acts as your always-on infrastructure, handling distribution while you’re offline.

Hardware: Orange Pi 6 Plus

Recommended specs:

• 8-core ARM CPU: Powerful enough for CRDT operations and encryption
• 4GB-16GB RAM: Sufficient for multiple concurrent connections
• NPU included: Future AI capabilities (image processing, video transcoding, voice commands)
• Affordable: Cost-effective personal infrastructure
• Low power: Designed for always-on operation
• Your hardware: Physical possession, complete control

Minimum for testing:

• 2GB RAM
• 16GB storage
• Standard internet connection

Installation

Cross-Compile for Orange Pi (ARM64)

Build kunki CLI for Orange Pi:

# Install cross-compilation tools
cargo install cross

# Clone repository
git clone https://github.com/osvauld/osvauld
cd osvauld/kunki

# Cross-compile for ARM64
cross build --target aarch64-unknown-linux-gnu --release

# Binary at: target/aarch64-unknown-linux-gnu/release/kunki

Transfer to Orange Pi

Copy the binary to your Orange Pi:

# Copy to Orange Pi
scp target/aarch64-unknown-linux-gnu/release/kunki orangepi@orangepi.local:/home/orangepi/

# SSH to Orange Pi and install
ssh orangepi@orangepi.local
sudo cp /home/orangepi/kunki /usr/local/bin/
sudo chmod +x /usr/local/bin/kunki

Initialize Node

Create cryptographic identity and database:

kunki init --username "your-node-name" --passphrase "your-secure-passphrase"

This generates:

• Ed25519 keys (PGP certificate for encryption, Permit signing, P2P connections)
• SQLite database (encrypted local storage)
• Node identity

Start Node Service

Run the personal node:

kunki start --passphrase "your-secure-passphrase"

The node:

• Establishes P2P listener on Iroh network
• Waits for peer connections
• Processes incoming sync requests
• Merges CRDT operations
• Caches updates from users
• Sends resource updates to connected peers

Run as service: For production, configure kunki to run as a systemd service for automatic startup and restart.

What Happens When Node Runs

Resource Updates

When you publish content from desktop to node:

1. Desktop syncs resource to node via Osvauld protocol
2. Node stores resource in encrypted database
3. Node sends updates to connected users
4. Users receive updates via CRDT sync

Caching User Updates

When users interact with your content:

1. Users send updates to node (comments, form submissions, edits)
2. Node caches updates in local database
3. Node merges updates using Loro CRDT
4. Node sends merged updates back to publisher when online

Conflict-Free Merging

Node uses Osvauld protocol for CRDT operations:

• Loro CRDT guarantees convergence
• Multiple users can edit simultaneously
• Node merges all changes conflict-free
• Everyone converges to same state

Generating Access Tokens

Create Permits for users to access specific folders:

kunki folder-token --passphrase "your-passphrase" --folder-id "folder-uuid-here"

This generates a base64-encoded connection string containing the Permit and connection details. Share this string with users via email, chat, or any communication channel.

See Handshake Mechanism for details on how connection strings establish trusted connections.

Node Operations

Publishing Flow

1. Create content in Sthalam desktop app
2. Publish to personal node via P2P sync
3. Node stores encrypted content
4. Node distributes to users with valid Permits

User Interaction Flow

1. User connects with connection string (contains Permit)
2. Node validates Permit
3. Node sends resources user is authorized to access
4. User interacts (view, comment, submit forms)
5. Node caches user updates
6. Node merges updates with other users’ changes
7. Node sends merged updates to publisher

Sync Protocol

Node uses Osvauld protocol state vector sync:

• Local-first rendering (instant for users)
• State vector exchange (only send missing diffs)
• Bidirectional sync (for comments, collaborative editing)
• Unidirectional sync (for read-only content)
• Append-only sync (for form submissions)

Current Status

Implemented:

• kunki CLI for node management
• P2P infrastructure (Iroh)
• Permit-based authorization
• Loro CRDT synchronization
• Resource distribution
• Update caching and merging
• Orange Pi 6 Plus support (ARM64)

Experimental:

• Security model still evolving
• No production optimizations
• Basic logging

Planned:

• Session-based key sharing
• Advanced monitoring
• Resource optimizations

Security Model

Current POC:

• Node receives full access to shared content
• Persistent decryption keys stored on node
• Standard peer synchronization

Planned production:

• Session-based key sharing
• Temporary access during active sessions
• No persistent keys on node

Community & Support

Get help:

• Telegram: t.me/osvauld
• GitHub Issues: github.com/osvauld/osvauld/issues
• Email: abe@osvauld.com

Security Disclosure

Found a security vulnerability? Email abe@osvauld.com instead of opening a public issue.

---

Your personal node. Your infrastructure. Your sovereignty.