Discover Operations

Sietch's discovery mechanisms allow vaults to find and connect with each other, even in environments with limited or no internet connectivity. This page explains how discovery works and how to effectively use its features.

Understanding Discovery Mechanisms

Sietch employs several methods to find peers:

Gossip Protocol

Lightweight UDP broadcast messages that help vaults announce their presence on local networks without central servers.

Manual Peering

Direct specification of known peer IP addresses for environments where automatic discovery isn't possible or desired.

Planned Extensions

Future versions may include Bluetooth, NFC, and QR-code based discovery for offline sharing scenarios.

Basic Discovery Command

sietch discover

The core command for finding other vaults on your local network.

This command sends UDP broadcast messages on your local network and listens for responses from other Sietch vaults. Results show the vault ID, name, and IP address of discovered peers.

Options:

# Discover peers on local network
sietch discover

# Search longer for peers
sietch discover --timeout 10s

# Show verbose discovery information
sietch discover --verbose --json

Managing Peers Manually

sietch peer

When automatic discovery isn't possible, you can manually manage peer connections.

• Add known peers by IP address or hostname
• List currently known peers
• Remove peers that are no longer needed
• Mark peers as trusted for automatic sync

Core Peer Commands:

# Add a known peer
sietch peer add 192.168.1.42

# Add a peer with custom name
sietch peer add 192.168.1.42 --name field-laptop

# List all known peers
sietch peer list

# Remove a peer
sietch peer remove 192.168.1.42

Advanced Discovery Features

Discovery Modes

Sietch offers different discovery modes for different environments:

• Broadcast: Default mode, sends UDP broadcasts (best for home/small networks)
• Multicast: Uses IP multicast for more efficient discovery in larger networks
• Static: Uses only manually configured peers (for high-security environments)
• Hybrid: Combines methods for maximum discovery potential

Persistent Discovery

Keep discovery running to find peers as they come online:

• Continuously watches for new peers joining the network
• Automatically updates the peer list
• Great for dynamic environments where peers come and go

Discovery Configuration

Configure discovery behavior in your vault settings:

Troubleshooting Discovery

• No peers found: Check network settings, firewall rules, and that other vaults are running
• Peers visible but unreachable: Check for firewall rules blocking the sync port
• Discovery too slow: Adjust timeout settings or use manual peering
• Too many peers found: Use filters to limit discovery scope

Discovery Diagnostics

This command provides detailed information about your network configuration, discovery capabilities, and potential issues.

Practical Discovery Scenarios

Journalist Field Kit

# Discover only trusted field devices
sietch discover --filter-name "field-kit-*"

# Add trusted peer manually when UDP is blocked
sietch peer add 192.168.1.100 --name trusted-editor --trusted

Research Team Collaboration

# Set up a persistent discovery service
sietch discover --watch --auto-add-peers

# Export discovered peers to share with offline team members
sietch peer export --discovered-since 2h > discovered-peers.json