Skip to main content
Documentation

Getting Started

Everything you need to install, configure, and use The Annex.

Installation

Download

Grab the latest TheAnnex.dmg or TheAnnex.zip from GitHub Releases, open the DMG, and drag The Annex to your Applications folder.

Build from Source

git clone https://github.com/ry4nolson/TheAnnex.git
cd TheAnnex
./build.sh

The app will be compiled, signed (ad-hoc), installed to ~/Applications/TheAnnex.app, and launched automatically.

Requirements

  • macOS 12.0 (Monterey) or later
  • Xcode Command Line Tools (build from source only)
  • Access to a NAS with SMB shares

Getting Started

  1. Launch The Annex — it appears in your menu bar. The welcome screen walks you through first-time setup.
  2. In General, click Add NAS → Scan Network to auto-discover your NAS via Bonjour.
  3. Enter credentials and shares, click Add.
  4. Go to Sync Folders → Add Folder → pick a preset or custom folder.
  5. Click Sync All or let the automatic check interval handle it.

Features

Sync Engine

  • Queue-based sync with up to 2 concurrent transfers
  • One-way sync: Local → NAS (rsync with --update)
  • Per-folder or sync-all, cancel individual or all
  • Progress tracking and bandwidth throttling

Symlink Mode

  • Replace local folders with symlinks to the NAS after syncing
  • NAS goes offline → symlink removed, local copy restored automatically
  • NAS comes back → local changes synced, symlink re-created
  • macOS-protected folders (Desktop, Documents, Pictures) run in sync-only mode automatically

Monitoring

  • Live connection quality (latency, packet loss) per NAS
  • Disk space monitoring with progress bars
  • Auto-mount SMB shares when NAS comes online
  • Configurable check intervals (30s to 30min)

Interface Tabs

  • General — NAS devices, discovery, monitoring dashboard
  • Sync Folders — sync pair list with status, clickable paths
  • Activity Log — searchable, filterable log with export
  • Statistics — transfer metrics, charts (macOS 13+)
  • Advanced — bandwidth, WiFi filtering, power, rsync flags
  • About — version, update check, changelog

Troubleshooting

NAS Won't Connect

  1. Verify hostname: ping YourNAS.local
  2. Check credentials
  3. Ensure SMB is enabled on the NAS

Sync Fails

  1. Check the Activity Log for errors
  2. Verify NAS paths exist and are writable
  3. Ensure sufficient disk space

Shares Won't Mount

  1. Try mounting manually in Finder: smb://YourNAS.local/share
  2. Check firewall settings
  3. Review Activity Log for mount errors

NAS Not Found in Scan

  1. Ensure your NAS advertises SMB via Bonjour/mDNS
  2. Check that both devices are on the same network/subnet
  3. Try entering the hostname manually