Features

Core Features

Recovery And Restore

• 12-word recovery phrase generated by buddydrive setup-recovery
• Master key derived from that phrase and stored in local config
• Encrypted config backup synced to the relay
• Config restore via buddydrive recover
• File restore through normal sync after the recovered machine starts again

Peer-to-Peer Architecture

No central sync account. No vendor lock-in.

Your Machine <--direct or relay--> Buddy's Machine

• Relay API discovery for finding buddies via pairing-code-derived keys
• Deterministic initiator selection — the side without a public address initiates; if both same reachability, lower buddy UUID initiates
• Relay fallback when both sides store the same pairing code
• Always accept incoming — incoming connections from known buddies are accepted regardless of sync time
• Yamux multiplexing for multiple streams

Automatic File Sync

• File change detection for new, modified, and deleted files
• Move detection — renamed files detected via content hash, no re-upload needed
• Incremental sync so only changed data is transferred
• Chunked transfer in 64KB blocks
• Symlink support — symlink targets are preserved across sync
• LZ4 compression when it reduces payload size

Encrypted Backup

When folder encryption is enabled (the default), filenames and file contents are encrypted before being stored on your buddy's machine:

• Deterministic path encryption — same filename always encrypts to the same ciphertext, enabling move detection without re-uploading
• Random content nonces — each 64KB chunk is encrypted with a fresh random nonce, preventing nonce reuse across file versions
• Opaque storage — your buddy sees only encrypted blobs, not your filenames or file contents
• Unencrypted sharing mode — set encrypted = false to share files plaintext for collaboration

Restore Missing Files

If a file still exists on your buddy but is missing locally, BuddyDrive can recreate it during the next successful sync. Restored files are hash-verified after write.

Move and Delete Detection

• Moved files — detected via content hash matching; the buddy renames the encrypted path without re-uploading
• Deleted files — propagated to the buddy with a delete instruction
• Content-hash-based comparison — streaming blake2b hash used for change detection, not just mtime/size

Folder Policies

• Append-only mode avoids remote overwrites of existing local files
• Missing files can still be restored even in append-only mode
• Buddy-specific folders restrict a folder to a chosen buddy
• Per-folder names keep sync targets readable in the CLI and GUI

Real-Time Status

GTK4 desktop application shows:

• Connection status for each buddy
• Sync progress per folder
• File counts and bytes transferred
• Recent activity log

The CLI provides the same core configuration and recovery flow for headless systems.

Security Features

Pairing Code

1. Generate a pairing code on your machine
2. Share it with your buddy
3. They store it when adding you as a buddy
4. The same stored code is reused for relay fallback

Direct Transport Encryption

Direct libp2p peer connections use Noise transport encryption. Recovery config blobs synced to the relay are encrypted with the recovery master key before upload. Folder contents are encrypted with XSalsa20-Poly1305 before being stored on the buddy's machine.

Recovery Metadata

• A public_key lookup value in [recovery]
• A locally stored master_key
• An encrypted config blob in the relay API

Sync Features

Conflict Handling

• Owner-authoritative by default — the file owner's current version always replaces the storage copy
• Append-only mode avoids remote overwrites of existing local files
• Missing files can still be restored even in append-only mode
• Move detection avoids full re-upload when a file is renamed
• No built-in version history yet

Large File Support

• Files split into 64KB chunks
• LZ4 compression when it reduces payload size
• Optional bandwidth limit through config

Platform Support

Linux

Build from source today. GTK4 GUI with desktop integration on Linux.

macOS

Build from source.

Windows

Build from source.

Headless

Run on servers, NAS boxes, or Raspberry Pi with the CLI only.

Technical Details

Built With

• Nim - systems programming language
• libp2p - peer-to-peer networking
• libsodium - encryption (XSalsa20-Poly1305) and key derivation
• GTK4 - desktop GUI
• SQLite - runtime status and file tracking

Network Requirements

• Outbound internet access
• Direct mode needs a reachable public TCP address
• Relay mode needs a configured relay service and matching pairing code on both sides
• IPv4 and IPv6 supported

Limitations

• Background sync depends on peers connecting successfully
• One buddy per folder today
• recover restores config from the relay path today; buddy-backed config fetch is not implemented yet
• export-recovery shows stored recovery metadata, not the original phrase
• init --with-recovery is shown in help but returns an error if used; use init then setup-recovery
• No mobile apps yet
• No file versioning yet

See How It Works for architecture details.