Documentation - BuddyDrive

Quick Start

Prerequisites

Linux, macOS, or Windows
Internet connection
A friend with BuddyDrive installed

Install

Linux:

git clone https://github.com/gokr/buddydrive
cd buddydrive
nimble build

macOS:

git clone https://github.com/gokr/buddydrive
cd buddydrive
nimble build

Windows:

git clone https://github.com/gokr/buddydrive
cd buddydrive
nimble build

Initialize

buddydrive init

This creates:

Buddy ID - a UUID that uniquely identifies your instance
Buddy Name - a human-readable name
Configuration file at ~/.buddydrive/config.toml

Pair With a Buddy

On your machine:

buddydrive add-buddy --generate-code

On your buddy's machine:

buddydrive add-buddy --id <your-buddy-id> --code ABCD-EFGH

The pairing code is used for both pairing confirmation and relay fallback.

Add a Folder

buddydrive add-folder ~/Documents --name docs

Options:

--name - friendly name for the folder
--no-encrypt - disable the folder's encryption flag in config
--append-only - only accept new incoming files for that folder
--buddy <id> - restrict the folder to a specific buddy

Set Up Recovery

Enable recovery on the machine you want to protect:

buddydrive setup-recovery

BuddyDrive shows a 12-word recovery phrase, asks you to verify part of it, stores recovery metadata in config.toml, and syncs an encrypted config blob to the relay.

Restore On a New Machine

On a replacement machine:

buddydrive recover
buddydrive start

Enter the same 12-word recovery phrase. If relay recovery succeeds, BuddyDrive restores your config locally. Starting the daemon then lets normal sync recreate missing files.

Current limitation: the CLI prompts for buddy fallback details if relay recovery fails, but that buddy-backed fetch path is not implemented yet. Recovery works via the relay path only.

Start the Daemon

buddydrive start

Optional:

--port <control-port> - change the local control API port
--daemon - accepted, but currently continues in the foreground

Per-Buddy Sync Time

Each buddy can have an optional sync time that controls when to initiate connections. Incoming connections are always accepted:

buddydrive config set buddy-sync-time <buddy-id> 03:00

When empty (default), the daemon initiates whenever it discovers a buddy address.

Connectivity Notes

BuddyDrive connects peers using deterministic initiator selection: the side without a public address initiates (it dials the public side directly), or the side with the lower buddy UUID if both are the same reachability. Incoming connections from known buddies are always accepted. Connectivity options:

Direct connection with a public TCP address
Relay fallback using the stored pairing code

For direct connections, forward the configured listen_port on your router and set [network].announce_addr in ~/.buddydrive/config.toml to a public multiaddr such as:

announce_addr = "/ip4/203.0.113.10/tcp/41721"

For relay fallback:

buddydrive config set relay-base-url https://api.buddydrive.org
buddydrive config set relay-region eu

The public EU TCP relay is relay-eu.buddydrive.org:19447.

Check Status

buddydrive status

Current CLI Limitations

buddydrive start --daemon is not fully implemented yet
buddydrive stop is a placeholder command today
buddydrive status shows configured state, not live daemon connectivity
buddydrive connect does not perform a manual direct dial yet
buddydrive export-recovery shows stored recovery metadata, not the original 12-word phrase
buddydrive init --with-recovery is shown in help but returns an error if used; use init then setup-recovery

GUI

Launch

buddydrive-gui

Features

Status panel - daemon running, identity, uptime
Folders list - configured folders and sync status
Buddies list - paired buddies and their stored configuration
Add folder dialog - select path, name, encryption flag, and append-only mode
Pair dialog - generate or enter pairing details
Recovery section - setup, recover, export, and sync config

CLI Reference

Commands

buddydrive init                        Initialize BuddyDrive
buddydrive config                      Show configuration
buddydrive config set <key> ...        Update configuration values
  relay-base-url <url>                Set relay discovery URL
  relay-region <region>               Set relay region (eu, us, local)
  storage-base-path <path>           Set incoming storage base path
  bandwidth-limit <kbps>             Set bandwidth limit (0 = unlimited)
  buddy-pairing-code <id> <code>     Set buddy pairing code
  buddy-name <name>                  Set buddy display name
  buddy-sync-time <id> <HH:MM>       Set buddy sync time (empty = always)
  folder-append-only <name> on|off   Toggle folder append-only mode
buddydrive add-folder <path>           Add folder to sync
  --name <name>                        Folder name
  --no-encrypt                         Disable folder encryption flag
  --append-only                        Only sync new files into that folder
  --buddy <id>                         Restrict folder to buddy
buddydrive remove-folder <name>        Remove folder
buddydrive list-folders                List configured folders
buddydrive add-buddy                   Pair with a buddy
  --generate-code                      Generate pairing code
  --id <buddy-id>                      Buddy ID to pair with
  --code <code>                        Pairing code from buddy
buddydrive remove-buddy <id>           Remove buddy
buddydrive list-buddies                List paired buddies
buddydrive connect <address>           Manual connect placeholder
buddydrive start                       Start sync daemon
  --port <control-port>                Override control API port
  --daemon                             Accepted but stays foreground
buddydrive stop                        Stop placeholder command
buddydrive status                      Show configured status
buddydrive logs                        Show recent logs
buddydrive setup-recovery              Generate recovery phrase and sync encrypted config
buddydrive recover                     Restore config from recovery phrase
buddydrive sync-config                 Manually sync encrypted config to relay/buddies
buddydrive export-recovery             Show stored recovery metadata
buddydrive help                        Show help

Examples

# Pair with a buddy
buddydrive add-buddy --generate-code
buddydrive add-buddy --id abc123 --code XYZ-789

# Add folders
buddydrive add-folder ~/Photos --name photos
buddydrive add-folder ~/Documents --name docs --append-only

# Configure relay fallback
buddydrive config set relay-base-url https://api.buddydrive.org
buddydrive config set relay-region eu
buddydrive config set buddy-pairing-code abc123 ABCD-EFGH

# Set per-buddy sync time
buddydrive config set buddy-sync-time abc123 03:00

# Set bandwidth limit
buddydrive config set bandwidth-limit 500

# Toggle append-only on a folder
buddydrive config set folder-append-only docs on

# Set up recovery
buddydrive setup-recovery

# Restore on a new machine
buddydrive recover

# Check what's configured
buddydrive list-folders
buddydrive list-buddies
buddydrive config

Configuration

Config stored at ~/.buddydrive/config.toml:

[buddy]
name = "Alice"
id = "fcd6295c-a912-44d4-a27b-ad898795207d"

[recovery]
enabled = true
public_key = "6J8h2qFvExampleRecoveryKey"
master_key = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"

[network]
listen_port = 41721
announce_addr = "/ip4/203.0.113.10/tcp/41721"
relay_base_url = "https://api.buddydrive.org"
relay_region = "eu"
storage_base_path = ""
bandwidth_limit_kbps = 0

[[folders]]
id = "f47ac10b-58cc-4372-a567-0e02b2c3d479"
name = "docs"
path = "/home/alice/Documents"
encrypted = true
append_only = false
folder_key = "a1b2c3d4e5f6..."
buddies = ["bob-uuid"]

[[buddies]]
id = "bob-uuid"
name = "Bob"
pairing_code = "ABCD-EFGH"
sync_time = "03:00"
added_at = "2026-04-10T12:00:00Z"

Files

Location	Purpose
`~/.buddydrive/config.toml`	Configuration
`~/.buddydrive/state.db`	Runtime state
`~/.buddydrive/index.db`	File index
`~/.buddydrive/buddydrive.log`	Logs
`~/.buddydrive/port`	Control API port

Troubleshooting

Daemon won't start

buddydrive logs
buddydrive config

Can't connect to buddy

Both peers need internet access
Both peers need buddydrive start running
Check stored buddies with buddydrive list-buddies
For direct mode, verify port forwarding and announce_addr
For relay mode, verify relay-region, relay-base-url, and matching pairing codes

Files not syncing

Check daemon logs with buddydrive logs
Check folder configuration with buddydrive list-folders
Remember buddydrive status does not show live connection state yet
Missing files are restored through normal sync after connectivity returns

Next Steps

Read Features for capabilities
Read Security for current security scope
Read How It Works for architecture