Getting Started

From zero to Bitcoin-timestamped backups in 10 minutes

What is Borg?

BorgBackup (or just "Borg") is a backup program that's smart about storage. Instead of copying everything every time, it only stores what's changed.

Deduplication

Have 10 copies of the same photo? Borg stores it once. Back up daily? Only changes are stored.

Compression

Your data is compressed automatically. A 100GB backup might only take 30GB of space.

Encryption

Optional AES-256 encryption. Even if someone gets your backup, they can't read it.

What does borg-anchor add?

borg-anchor wraps Borg and adds Bitcoin timestamping. After each backup, the fingerprint (hash) of your data is recorded on the Bitcoin blockchain. This creates mathematical proof that your backup existed at a specific point in time.

Install Prerequisites

You'll need three things installed. This takes about 5 minutes.

Install BorgBackup

The backup engine that does the heavy lifting.

# Ubuntu/Debian
sudo apt install borgbackup

# macOS
brew install borgbackup

# Verify installation
borg --version

Install Node.js 18+

Required to run borg-anchor.

# Check if you have it
node --version

# If not, install via your package manager or:
# https://nodejs.org/

Install borg-anchor

npm install -g borg-anchor

# Verify installation
borg-anchor --version

Install blocktrails (for Bitcoin anchoring)

This handles the Bitcoin transaction side.

git clone https://github.com/blocktrails/blocktrails.git
cd blocktrails
npm install

See blocktrails repo for full setup.

Quick Win #1: Your First Backup 5 min

Let's back up your Documents folder.

Initialize a backup repository

# Create and initialize the backup location
borg-anchor init ~/backups

This creates a new directory with a Borg repository inside. You'll see output like:

  Initializing borg-anchor in /home/you/backups

  Creating borg repo: /home/you/backups/repo
  ✓ Borg repository created
  ✓ Config saved: .borg-anchor.json
  ✓ Git initialized

Create your first backup

# Back up ~/Documents to ~/backups
borg-anchor backup ~/Documents ~/backups --name my-backup --no-anchor

You did it!

Your data is now safely backed up with Borg. The --no-anchor flag skipped Bitcoin timestamping for this test run.

See what you've backed up

borg-anchor list

You'll see your backup with its unique fingerprint (SHA-256 hash).

Quick Win #2: Fund Your Testnet Wallet 5 min

Before you can anchor on Bitcoin, you need a keypair and some testnet coins.

What's testnet?

Bitcoin testnet is a separate blockchain for testing. The coins have no value, so you can experiment freely. borg-anchor uses testnet4 (tbtc4) by default.

Generate a keypair

You need a hex private key to sign Bitcoin transactions. Use our helper script or generate one manually:

# Option 1: Use the helper script (recommended)
# Download and run from the borg-anchor repo
curl -sL https://raw.githubusercontent.com/solid-live/borg-anchor/gh-pages/scripts/keygen.sh | bash

# Option 2: Generate manually with openssl
openssl rand -hex 32

This outputs a 64-character hex string like:

a1b2c3d4e5f6789...your64characterhexkey...9876543210ab

Save your private key!

Copy this key somewhere safe. If you lose it, you lose access to your testnet funds and UTXO chain.

Configure borg-anchor with your key

# Navigate to your backup repository
cd ~/backups

# Store the private key in git config (local to this repo)
git config nostr.privkey YOUR_64_CHAR_HEX_KEY

# Initialize blocktrails (creates .blocktrail.json)
blocktrails init

Get your testnet address

Use blocktrails to derive your address from the private key:

# Show your wallet info including address
blocktrails show

Copy the testnet4 address that's displayed (starts with tb1... or similar).

Get free testnet coins from a faucet

Visit one of these testnet4 faucets and paste your address:

Testnet4 Faucet List - curated list of working faucets

Request a small amount (0.001 tBTC is plenty for many anchors).

Verify your balance

# Check that the coins arrived
blocktrails show

Wait a few minutes for the transaction to confirm. You should see a balance.

Wallet funded!

You now have testnet coins ready to anchor backups. Each anchor uses a small amount, so this will last for many backups.

Quick Win #3: Bitcoin Timestamping 5 min

Now let's anchor a backup on Bitcoin testnet.

Create a Bitcoin-timestamped backup

# Back up WITH Bitcoin anchoring
borg-anchor backup ~/Documents ~/backups --name my-backup-anchored

The output will show the fingerprint being anchored:

  Creating backup: my-backup-anchored
  Source: /home/you/Documents
  Repo: /home/you/backups/repo

  Fingerprint: 7a3b9c...

  Anchoring on Bitcoin...
  ✓ Backup complete!

Verify it's anchored

borg-anchor verify my-backup-anchored ~/backups

Your backup is now on Bitcoin!

The fingerprint of your data has been recorded in a Bitcoin transaction. Anyone can verify that this exact data existed at the time of the block.

Quick Win #4: Restore Your Data 2 min

The whole point of backups - getting your data back.

Restore to a new location

# Restore your backup to ~/restored/
borg-anchor restore my-backup ~/restored ~/backups

Check the restored files

ls ~/restored/
# Your files are under the original path structure:
ls ~/restored/home/you/Documents/

Data restored!

Borg preserves the full path structure. Your files are exactly as they were when backed up.

Key Concepts

Repository vs Archive

A repository is where all your backups are stored (like ~/backups/repo). An archive is a single backup within that repository (like my-backup).

Repository: ~/backups/repo/
├── Archive: my-backup     (Jan 1)
├── Archive: second-backup    (Jan 2)
└── Archive: weekly-backup    (Jan 7)

Fingerprints

Every archive has a unique fingerprint - a SHA-256 hash of its contents. If even one byte changes, the fingerprint is completely different. This fingerprint is what gets anchored on Bitcoin.

The Anchor Chain

borg-anchor uses a chained UTXO trail, meaning each backup links to the previous one. This creates an unbroken chain of proofs you can reconstruct at any time.

Networks

tbtc4 (testnet4) - Default. Free to use. Great for testing and non-critical backups.
btc (mainnet) - Real Bitcoin. Use for important data that needs permanent, trusted timestamps.

# Use mainnet for production
borg-anchor init ~/important-backups --network btc

Command Reference

# Initialize a new backup repository
borg-anchor init ~/backups
borg-anchor init ~/backups --encryption repokey  # with encryption
borg-anchor init ~/backups --network btc         # use mainnet

# Create backups
borg-anchor backup ~/mydata ~/backups            # auto-named backup-YYYY-MM-DD
borg-anchor backup ~/mydata ~/backups --name daily  # custom name
borg-anchor backup ~/mydata ~/backups --no-anchor   # skip Bitcoin
borg-anchor backup ~/mydata ~/backups --dry         # dry run

# View backups
borg-anchor info                                 # dashboard of all projects
borg-anchor list ~/backups                       # list all archives
borg-anchor show ~/backups                       # show config & trail status

# Verify & restore
borg-anchor verify my-backup ~/backups           # check if anchored
borg-anchor restore my-backup ~/dest ~/backups   # restore files

Next Steps

You now know the basics. Here's where to go next:

Full Documentation BorgBackup Docs blocktrails GitHub

Troubleshooting

borg: command not found

BorgBackup isn't installed or not in your PATH. Install it with your package manager.

blocktrails CLI not found

You need to install blocktrails. See the repo for instructions.

No config found

You're not in a borg-anchor directory. Either cd into your backup folder or run borg-anchor init first.

Backup not anchored

Make sure you've set up your private key with git config nostr.privkey and have testnet coins if needed.