Glossary

Glossary

Terms used across the wiki and the repo. Alphabetical. If a term is missing, open an issue or a PR.

---

Adaptive polling. UniDrive doesn't poll its providers at a fixed interval. It cycles between active (something just changed, check again soon), normal (steady state), and idle (nothing's changed for a while, slow down). On Linux, file changes also trigger an immediate poll via inotify.

ADR — Architecture Decision Record. A short Markdown file documenting a single decision (why we chose X over Y, what alternatives were considered, what we'd revisit it under). The repo's ADRs live under docs/adr/.

Apache-2.0. The open-source license UniDrive is published under. You can use, modify, and redistribute it, including commercially. You cannot claim trademark over the work, and you must preserve the copyright notice.

Backlog. The repo's list of open work, kept in docs/backlog/BACKLOG.md. Closed items move to CLOSED.md. Each item has a UD-### ID that lives forever (never reused).

CLI — Command-Line Interface. The unidrive command you type in a terminal.

Daemon. A long-running background process. UniDrive's daemon (unidrive sync --watch) is what watches the filesystem and syncs changes; it's started by systemd as a user service.

Delta API / delta sync. A way for a cloud provider to tell you "what changed since you last asked," instead of you walking the entire tree. Microsoft Graph and the local filesystem support this directly; S3 / SFTP / WebDAV simulate it via snapshot-and-diff.

Encryption-at-rest. Files stored in encrypted form on disk (or in the cloud), so reading the storage gives you ciphertext instead of plaintext. UniDrive's optional vault feature provides this for the cloud-side; the local filesystem is whatever your OS provides (LUKS, FileVault, etc.).

Hash. A short fingerprint of a file's contents. Two files with the same hash are (overwhelmingly likely) the same file. UniDrive uses hashes to detect "is this the same file we already have?"

HVD. "High-Value Dataset" — an EU open-data classification UniDrive itself doesn't use, but appears in the codebase due to the dati.gov.it MCP. Not relevant to most users.

Hydrate / dehydrate. A hydrated file is one whose actual bytes are physically on your local disk. A dehydrated placeholder is a file the system knows about but whose bytes haven't been downloaded yet (it's a 0-byte stub). UniDrive can keep large files dehydrated until you open them, saving disk space.

IPC — Inter-Process Communication. The way two programs on the same machine talk to each other. UniDrive uses Unix-domain sockets (a file-based local-only protocol).

JVM — Java Virtual Machine. The runtime UniDrive runs on. UniDrive needs JVM 21 or newer.

MCP — Model Context Protocol. A standardised way for an LLM (a chatbot like Claude or GPT) to call functions on your computer. UniDrive ships an MCP server with 15 tools so an LLM can drive the sync, list files, resolve conflicts, etc.

MVP — Minimum Viable Product. The version of a tool that's good enough to use for the basic case, without being feature-complete. UniDrive's MVP is "sync localfs + s3 + sftp reliably on Linux."

NDJSON — Newline-Delimited JSON. One JSON object per line. UniDrive's event stream over the Unix-domain socket is NDJSON.

OAuth / OAuth2. A way for an application (UniDrive) to ask for permission to access an account (your OneDrive) without ever seeing your password. The provider gives UniDrive a token it can use later. Tokens can be revoked at any time from the provider's settings page.

PKCE (pronounced "pixie") — Proof Key for Code Exchange. An OAuth extension that makes the authentication flow safe to do on a desktop computer (where there's no server-side secret to protect). UniDrive uses PKCE for OneDrive and HiDrive.

Placeholder. A 0-byte local file representing a real file that exists in the cloud. Reading the file (or running unidrive get) downloads the real bytes. See hydrate.

Profile. A named pairing of a provider type (e.g. onedrive) with credentials and a remote path. You can have multiple profiles in one config file ("my-personal-onedrive", "work-sftp", "backup-s3"). Each profile has its own state database and its own daemon.

S3 / S3-compatible. Amazon's object-storage protocol, also implemented by MinIO, Garage, Backblaze, Wasabi, Synology, Hetzner, and many others. UniDrive's S3 provider works with all of them.

Sandbox / dehydrated placeholder. See placeholder.

SDK — Software Development Kit. A library that wraps a provider's API in a more convenient form. UniDrive deliberately avoids most provider SDKs and talks to the HTTP APIs directly, to keep the code auditable.

SFTP — SSH File Transfer Protocol. A way to copy files over an SSH connection. Older but very widely supported; works against any server that runs OpenSSH (basically every Linux box).

SPI — Service Provider Interface. The Java/Kotlin pattern UniDrive uses to discover providers at runtime. Every provider module ships a metadata file declaring "here's the class that implements CloudProvider," and UniDrive's ServiceLoader finds them.

SQLite. The small embedded database UniDrive uses to track which files it knows about. One file per profile, no separate database server.

STRIDE. A threat-modelling framework: Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of privilege. The security-formal version of Threat Model In Plain Language lives in SECURITY.md and follows STRIDE.

Systemd user service. The way a Linux daemon gets started under your user account (not root) and survives across logouts. UniDrive installs ~/.config/systemd/user/unidrive.service.

TOML. A human-readable config file format. UniDrive's config file (~/.config/unidrive/config.toml) is TOML.

Token. A digital key your cloud provider gives UniDrive after you log in via OAuth. Tokens expire and get refreshed automatically. They live in ~/.config/unidrive/{profile}/token.json with restricted file permissions.

UD-###. A backlog ticket ID. Used everywhere in the repo and the wiki. The ID maps to one (sometimes more) entries in docs/backlog/BACKLOG.md or CLOSED.md.

UDS — Unix-Domain Socket. A local-only socket that lives as a file on disk. UniDrive's daemon publishes its event stream on a UDS at $XDG_RUNTIME_DIR/unidrive-<profile>.sock.

Vault. UniDrive's optional client-side encryption layer. With the vault on, files are encrypted on your computer before they leave for the cloud. The cloud provider sees ciphertext. See Threat Model In Plain Language.

Webhook. A way for a cloud provider to push you a notification when something changes, instead of you polling. Only OneDrive supports this in the providers UniDrive talks to.

WebDAV. An HTTP-based file-access protocol. Nextcloud, ownCloud, Synology DSM, many NAS boxes, and various other servers speak it.