Skip to content

For Linux Users

Jump to bottom
Gernot Krost edited this page May 1, 2026 · 1 revision

For Linux Users

This page is for you if you've used rclone, the OneDrive Linux client, rsync, Insync, or have just been making do with the web UI on Linux because the official desktop client doesn't ship for your distro.

What UniDrive is, in one paragraph

A daemon (unidrive sync --watch) plus a CLI (unidrive) plus an optional MCP server (unidrive-mcp) that talks to eight cloud-storage providers from a single config file. JVM 21 LTS, runs on systemd --user, ships as a single shadow JAR + a Bash launcher. State lives in a SQLite database at ~/.local/share/unidrive/{profile}/state.db.

Install

No prebuilt binaries yet — build from source:

git clone https://github.com/gkrost/unidrive.git
cd unidrive/core
./gradlew :app:cli:deploy :app:mcp:deploy

That puts unidrive and unidrive-mcp launchers under ~/.local/bin/ and the JARs under ~/.local/lib/unidrive/. A systemd user unit (~/.config/systemd/user/unidrive.service) is installed and started for you.

Make sure ~/.local/bin is on your PATH.

First sync

# 1. Edit the config file (TOML)
$EDITOR ~/.config/unidrive/config.toml

# 2. Authenticate the profile (browser-based for OAuth providers)
unidrive auth -p my-onedrive

# 3. Run the first sync
unidrive sync -p my-onedrive

A minimal config file:

[general]
sync_root = "/home/yourname/CloudStuff"
conflict_policy = "keep_both"

[profile.my-onedrive]
provider = "onedrive"
remote_path = "/"

Eight provider types are recognised: onedrive, s3, sftp, webdav, rclone, hidrive, internxt, localfs. See Provider Status for which ones are MVP-ready and which are preview.

Compared to other Linux sync tools

  • vs rclone — UniDrive has fewer providers (8 vs ~70+) but a real local sync engine with state tracking, conflict resolution, and a daemon mode. rclone is closer to a copy/mirror utility; UniDrive is closer to what the official client of each provider does on Windows/macOS, but for Linux. UniDrive has an rclone provider so you can use rclone backends from inside UniDrive when needed.
  • vs the official OneDrive Linux client (third-party abraunegg/onedrive) — that one is OneDrive-only. UniDrive can sync OneDrive and an SFTP server and an S3 bucket from one config file, with one daemon, one CLI.
  • vs rsync over cron — rsync doesn't speak OAuth or HTTP-based cloud APIs. For SFTP and local-to-local you can use either; for everything else rsync doesn't apply.
  • vs Insync (commercial) — UniDrive is open-source and Apache-2.0. No subscription, no account.

What works today

  • localfs, s3, sftp — MVP quality. Used in CI integration tests.
  • onedrive, webdav, rclone, hidrive, internxt — preview. They build, they have unit tests, and most operations work — but they don't gate the MVP release.

See Provider Status for the per-capability matrix.

Notable features

  • Bidirectional sync with conflict detection (keep-both or last-writer-wins, configurable per profile).
  • Pin rules — glob patterns that mark certain files as "always keep a real local copy"; everything else can be a 0-byte placeholder until you open it.
  • --dry-run for every operation so you can see what would happen first.
  • Adaptive polling — cycles between active/normal/idle delays so it's not hammering the API when nothing's changing.
  • unidrive log --watch streams structured sync events over a Unix-domain socket, NDJSON. Third-party tray applets / status bars can subscribe.
  • MCP server (unidrive-mcp) — 15 tools an LLM can call to drive the sync, list files, resolve conflicts, etc.

Where to go next

Clone this wiki locally