OneCloudRiver

Native. Fast. No intermediaries.

🇪🇸 Versión en español

---

⚠️ Notice about project origins

This project is heavily inspired by onedriver, the native FUSE filesystem for OneDrive created by @jstaf.

OneCloudRiver is not a GitHub fork — the amount of changes, complete architectural reorganization, and new features added make it an independent project with its own identity. However, we want to explicitly acknowledge onedriver's foundational work, without which this project would not exist.

---

OneCloudriver mounts your OneDrive as a native FUSE filesystem on Linux, allowing you to read, write, create, and delete files directly from your file manager (Nautilus, Dolphin, Thunar) and terminal.

Files are downloaded only when you need them. OneCloudriver gives you instant access to all your files and only downloads the ones you actually use—no waiting for hours while a sync client transfers your entire account. A file will only be re-downloaded if it has changed remotely on OneDrive and you access it again.

🚀 Features

• Full read-write — Create, Write, Mkdir, Rmdir, Unlink, Rename, Chmod, Touch
• Offline mode — Cached files available without Internet connection
• Delta sync — Remote changes automatically detected via Microsoft Graph
• Upload Manager — Asynchronous uploads with retries and concurrency control
• Smart cache — Metadata with TTL+LFU eviction, disk content with size-based eviction
• BoltDB persistence — Filesystem state preserved across sessions
• systemd service — Auto-mount on login (onecloudriver service install)
• Complete CLI — Operations without mounting: list, download, upload, info, mkdir, mv, cp, rm, rename
• Health check — Connectivity and token verification before mounting, with clear diagnostics
• Retry with backoff — Automatic retries on 429/503/network errors
• 80%+ test coverage — Unit, FUSE integration, fuzzing, and security audit

📦 Quick Installation

From binary

# Download latest release
wget https://github.com/FROSADO/onecloudriver/releases/download/v0.1.2/onecloudriver_linux_amd64.zip
unzip onecloudriver_linux_amd64.zip
sudo cp onecloudriver /usr/local/bin/

From .deb package

# Download and install the .deb package
wget https://github.com/FROSADO/onecloudriver/releases/download/v0.1.2/onecloudriver_0.1.2_amd64.deb
sudo dpkg -i onecloudriver_0.1.2_amd64.deb

Installing the .deb also registers the man page — try man onecloudriver after installation.

From .rpm package

# Download the .rpm package
wget https://github.com/FROSADO/onecloudriver/releases/download/v0.1.2/onecloudriver-0.1.2-1.x86_64.rpm

Install with your distro's package manager (requires fuse3, which is resolved automatically):

# Fedora / RHEL 8+ / Rocky Linux / AlmaLinux
sudo dnf install ./onecloudriver-0.1.2-1.x86_64.rpm

# RHEL / CentOS 7 (older)
sudo yum install ./onecloudriver-0.1.2-1.x86_64.rpm

# openSUSE
sudo zypper install ./onecloudriver-0.1.2-1.x86_64.rpm

The .rpm installs the binary to /usr/local/bin, the man page (man onecloudriver), the systemd user service template and the documentation under /usr/share/doc/onecloudriver/.

From source

git clone https://github.com/FROSADO/onecloudriver.git
cd onecloudriver
make build
sudo cp onecloudriver /usr/local/bin/

Requirements

• Go 1.25+
• FUSE 3 (libfuse3 or fuse3)
• Git (for building from source)

# Ubuntu/Debian
sudo apt-get install fuse3

# Fedora
sudo dnf install fuse3-libs fuse3

✅ Verifying release artifacts

Every GitHub release ships a signed checksum manifest plus per-artifact GPG signatures:

• SHA256SUMS — sha256 checksums of every artifact
• SHA256SUMS.asc — detached GPG signature of the manifest
• <artifact>.asc — detached GPG signature of each artifact
• public.key — the release signing public key

# Download all release assets into a directory (or grab them from the release page)
cd /tmp/release-check
gh release download v0.1.2 --repo FROSADO/onecloudriver

# 1. Import the release signing public key
#    (only needed once per machine)
gpg --import public.key

# 2. Verify the signature of the checksum manifest
#    → "Good signature from ..."
gpg --verify SHA256SUMS.asc SHA256SUMS

# 3. Verify the integrity of every artifact
#    → "...: OK" for each file
sha256sum -c SHA256SUMS

# 4. (Optional) Verify each artifact's detached signature
gpg --verify onecloudriver_linux_amd64.zip.asc onecloudriver_linux_amd64.zip

Tip

If the signature shows Good signature but warns the key is not certified, that is expected until you trust the key.

Note

Good signature proves the file was signed by that key, not that the key belongs to the project. Confirm the public key's fingerprint against a trusted channel (e.g. the release announcement) before relying on it.

📖 How the signing key is managed (setup, rotation, recovery): docs/RELEASE_SIGNING.md.

🔐 Authentication

# Add a Microsoft account
onecloudriver account add

# Browser will open at http://localhost:9090/callback
# Authorize the application and return to terminal

💾 Mount OneDrive

# Basic mount
onecloudriver mount ~/OneDrive -a user@outlook.com

# With custom cache configuration
onecloudriver mount ~/OneDrive -a user@outlook.com \
    --cache-dir ~/.cache/onecloudriver/custom \
    --cache-ttl 120s \
    --cache-max-entries 5000 \
    --cache-max-size 2GB

# Unmount (Ctrl+C in mount terminal, or)
fusermount3 -u ~/OneDrive

🖥️ CLI usage without mounting

# List files
onecloudriver list -a user@outlook.com /Documents

# Download
onecloudriver download -a user@outlook.com /photo.jpg -d ~/Downloads

# Upload
onecloudriver upload -a user@outlook.com -f ~/document.pdf --dest-path /Backup

# Create folder
onecloudriver mkdir -a user@outlook.com -n "New Folder" --dest-path /Documents

# Detailed info
onecloudriver info -a user@outlook.com /file.txt -o json

🔄 systemd service (auto-mount)

# Install service (auto-detects account if only one exists)
onecloudriver service install --mountpoint ~/OneDrive/%i

# Install and enable for specific account
onecloudriver service install --mountpoint ~/OneDrive/%i -a user@outlook.com --enable

# Install for ALL accounts
onecloudriver service install --mountpoint ~/OneDrive/%i --all --enable

# Manage
onecloudriver service status              # View status
onecloudriver service start user@outlook.com   # Start
onecloudriver service stop user@outlook.com    # Stop (clean unmount)
onecloudriver service stop --all               # Stop all

# Uninstall
onecloudriver service uninstall --all

🛠️ Development

# Build
make build

# Unit tests (mock, no FUSE)
make test-unit

# Integration tests (requires FUSE)
make test-integration

# All tests
make test-all

# Lint
make lint

# Security audit
make security-audit

# Coverage
make coverage

# Packaging
make dist          # Zip with binary + manual
make deb           # .deb package
make rpm           # .rpm package (requires rpm-build)

# Release
make release-check # Pre-flight release checklist (read-only)
make release       # Interactive release automation

# Full CI (as in GitHub Actions)
make clean && make build && make test-unit-short && make test-integration-short

🚀 Releases

The whole release process is automated with scripts/release.sh: it runs an interactive checklist, updates the CHANGELOG and publishes the release through the existing Release workflow.

# 1. Pre-flight checklist — everything to review before publishing (read-only)
make release-check

# 2. Full interactive flow
make release

What the script does:

1. Pre-flight checklist — gh authentication, repository, default branch, working tree state, unpushed commits, open PRs, recent CI status and last tag.
2. Optional PR merge — lists the open PRs targeting the default branch and offers to squash-merge them (gh pr merge --squash) before publishing, then switches to the default branch so the release is published from there.
3. Version selection — proposes the next patch version (e.g. 0.1.0 → 0.1.1).
4. CHANGELOG draft — generates a draft section from the commits since the last tag and opens it in your $EDITOR for review.
5. Version references update (optional) — refreshes the version badges and download URLs in README.md and README.es.md, plus any version references in the docs (docs/MANUAL*.md, man pages).
6. Commit + tag + push — commits the changes, creates the annotated tag vX.Y.Z and pushes it. The Release workflow then builds the artifacts (zip, .deb, .rpm) and creates the GitHub Release.
7. Monitoring — watches the workflow run and verifies the published release.

Requirements: GitHub CLI authenticated (gh auth login). The script is interactive; use bash scripts/release.sh --yes to auto-confirm the prompts (the editor still opens) or --check for the read-only checklist.

🏗️ Architecture

cmd/onecloudriver/     CLI (cobra): account, mount, list, download, upload, service...
    │
internal/
    ├── auth/          OAuth2 + keyring + account manager
    ├── graph/         Microsoft Graph HTTP client + retry/backoff
    └── fs/            FUSE filesystem
         ├── root.go              OneCloudFS: filesystem root
         ├── drive_item_node.go   FUSE node per file/folder
         ├── fs_ops.go            Operations: Mkdir, Create, Rename, Delete...
         ├── cache.go             InodeCache: metadata with TTL+LFU eviction + BoltDB
         ├── content_cache.go     ContentCache: disk content with eviction
         ├── delta.go             DeltaSync: Graph /delta polling
         ├── upload_manager.go    Async upload queue with retries
         └── mount.go             Mount: health check + lifecycle

📄 License

GPLv3 — see LICENSE for details.

🙏 Acknowledgments

This project would not exist without the pioneering work of onedriver by @jstaf and contributors. Much of the FUSE architecture and Graph client are based on its original design.