# How to Mount OneDrive with Rclone: VFS Cache, Throttling, and Agent Storage Mounting Microsoft OneDrive through Rclone exposes cloud files as a local filesystem via FUSE, but standard mount commands fail under random write workloads or heavy directory walks. Configuring full VFS caching and traffic pacing prevents I/O crashes and Microsoft Graph HTTP 429 rate limits. When scaling AI agent access across large repositories, scheduled workspace sync avoids the file locking and latency bottlenecks of local mounts. Source: https://fast.io/resources/rclone-mount-onedrive/ Author: [Tom Langridge](https://fast.io/authors/tom-langridge/) Last reviewed: 2026-10-07 ## How Rclone Mounts OneDrive Using FUSE and the Virtual File System Pointing a local script or autonomous agent at an unbuffered cloud storage mount will fail the moment the process attempts an in-place edit, a database lock, or a recursive directory scan. Rclone bridges this divide using Filesystem in Userspace (FUSE) to present remote cloud directories as a local directory tree, but cloud object stores do not natively behave like POSIX disks. Rclone mount OneDrive uses FUSE to expose a remote Microsoft OneDrive drive as a local filesystem mount, allowing local programs and AI agents to read and write remote files via standard POSIX system calls. On Linux and macOS systems, the kernel passes standard filesystem calls (`open`, `read`, `write`, `seek`, `close`) to the user-space rclone daemon. Rclone translates those system calls into HTTP REST operations targeting Microsoft Graph API endpoints. ``` +-------------------------------------------------------------------------+ | Local Applications and AI Coding Agents | | (POSIX calls: open, read, write, seek, close) | +-------------------------------------------------------------------------+ | (POSIX VFS) | +-------------------------------------------------------------------------+ | Linux Kernel FUSE | | (/dev/fuse driver) | +-------------------------------------------------------------------------+ | (FUSE User-Space) | +-------------------------------------------------------------------------+ | Rclone Mount Daemon Process | | (VFS Cache Layer + Sparse Disk Buffers + Pacer) | +-------------------------------------------------------------------------+ | (HTTPS / OAuth 2.0 REST Calls) | +-------------------------------------------------------------------------+ | Microsoft Graph API Endpoint | | (https://graph.microsoft.com) | +-------------------------------------------------------------------------+ | +----------------------+----------------------+ | | +-----------------------------+ +---------------------------+ | Personal OneDrive Account | | OneDrive for Business | | (Live SDK / Graph) | | (SharePoint Tenant) | +-----------------------------+ +---------------------------+ ``` ### The Mismatch Between Cloud Object APIs and POSIX Disks Local filesystems write arbitrary byte offsets directly to storage blocks. Cloud storage services treat files as discrete objects. Microsoft OneDrive does not expose block-level random access over HTTP. Writing a single byte in the middle of an existing file requires re-uploading the entire file payload or staging multipart chunk uploads. Without an intermediate virtualization layer, standard file operations fail: 1. **Random writes and in-place mutations:** Tools that open files with `r+` or perform `fseek` writes crash immediately when pointed at unbuffered mounts. 2. **Atomic file locking:** Applications that rely on POSIX byte-range locks or flock mechanisms (such as SQLite databases or vector cache indexes) cannot acquire hardware locks over remote HTTP requests. 3. **Truncation and append modes:** System flags like `O_APPEND` and `O_TRUNC` behave unpredictably over raw network endpoints when connection drops occur during payload transfers. To reconcile these differences, rclone implements a Virtual File System (VFS) abstraction layer. The VFS layer intercepts POSIX calls in memory and uses local disk caching to emulate standard disk behavior before committing finalized payloads to OneDrive. ## Configuring VFS Cache Modes for Interactive Writes and Agent Tooling Selecting the appropriate VFS cache mode dictates whether an rclone mount can handle read-write workloads or only basic sequential streaming. Rclone provides four distinct caching levels (`off`, `minimal`, `writes`, and `full`). For autonomous agents, development environments, and database scratchpads, selecting anything lower than `full` leads to unexpected process terminations. The operational differences across VFS modes determine file compatibility: | Cache Mode | Read Buffering | Write Buffering | Random Write Support | SQLite and Agent Compatibility | Local Disk Usage | | :--- | :--- | :--- | :--- | :--- | :--- | | `off` | Memory buffer only | None (direct streaming) | No (sequential only) | Incompatible | Zero disk cache | | `minimal` | Memory buffer only | Read-write files only | Partial | High error rate | Low | | `writes` | Direct remote stream | Writes buffered to disk | Yes (buffered writes) | Moderate (reads bypass disk) | Moderate | | `full` | Sparse files on disk | Full read-write cache | Yes (complete POSIX emulation) | Fully compatible | Controlled by max size | In `full` cache mode, all reads and writes are buffered through local disk storage. When an application opens a file, rclone allocates a local sparse file that matches the target file's total size on OneDrive. It downloads only the specific byte ranges requested by the application while keeping track of unread blocks. If a coding agent reads only a small header block from a large archive, rclone fetches that initial chunk rather than downloading the entire object. ### Recommended Production Mount Command According to the official [Rclone mount documentation](https://rclone.org/commands/rclone_mount/), the following command provides a stable configuration for mounting Microsoft OneDrive on Linux servers running automated tools or development agents: ```bash rclone mount onedrive: /mnt/onedrive \ --vfs-cache-mode full \ --vfs-cache-max-size 50G \ --vfs-cache-max-age 24h \ --vfs-read-chunk-size 64M \ --vfs-read-chunk-size-limit 512M \ --vfs-write-back 5s \ --buffer-size 32M \ --dir-cache-time 72h \ --poll-interval 1m \ --tpslimit 3 \ --tpslimit-burst 0 \ --allow-other \ --log-level NOTICE ``` ### Critical VFS Parameter Breakdown Configuring VFS cache parameters requires balancing local disk consumption against remote API latency: * **`--vfs-cache-mode full`:** Mandatory for applications that perform seeking, random writes, or concurrent read-write operations. Without full caching, SQLite databases, version repositories, and file-parsing agents fail with input/output errors. * **`--vfs-cache-max-size 50G`:** Enforces an upper ceiling on local disk space consumed by the cache directory. When the cache exceeds this threshold, rclone evicts the least recently accessed files first. Active open file handles are protected from eviction until closed. * **`--vfs-cache-max-age 24h`:** Sets the retention window for cached objects. Files that have not been read or written for the retention duration are pruned during background cache poll passes. * **`--vfs-read-chunk-size 64M` and `--vfs-read-chunk-size-limit 512M`:** Controls adaptive chunked reading. Rclone downloads data in chunk blocks, doubling the chunk size up to the configured limit for sustained sequential reads. This strategy avoids saturating network bandwidth on small random reads while maintaining high throughput for large file copies. * **`--vfs-write-back 5s`:** Sets the delay between when a process closes a modified file and when rclone begins uploading the finished object to OneDrive. This brief buffer allows tools that perform rapid successive writes to finish without generating multiple redundant upload versions. * **Filesystem requirements for sparse files:** The local directory designated for `--cache-dir` must reside on a filesystem that supports sparse files (such as ext4, XFS, Btrfs, APFS, or NTFS). Placing the cache on FAT32 or exFAT partitions disables sparse allocation, forcing rclone to pre-allocate full zeroed byte arrays that degrade write performance. ## Diagnosing and Preventing Microsoft Graph API Throttling Even with full VFS caching configured, background synchronization tasks and recursive directory traversals can quickly trigger Microsoft Graph API rate limits. When a script runs commands like `find /mnt/onedrive -type f` or an agent attempts to inspect large directory structures, rclone sends hundreds of metadata queries in rapid succession. Microsoft defends its multi-tenant infrastructure by returning HTTP status code 429 Too Many Requests. When throttling begins, rclone logs display warning messages indicating that request rates have exceeded backend quotas: ```text NOTICE: pacer: Reducing sleep to 10ms WARNING: pacer: Rate limited, increasing sleep to 2.4s WARNING: pacer: Rate limited, increasing sleep to 4.8s ERROR : path/to/document.pdf: Failed to copy: error 429: throttledRequest: The request has been throttled ``` Per the official [Microsoft Graph throttling guidelines](https://learn.microsoft.com/en-us/graph/throttling), request thresholds vary across endpoints, and high traffic volumes will cause writes to be throttled even while reads remain permitted. To keep an rclone mount responsive without hitting prolonged lockout windows, configure rate pacing and register a dedicated application ID in Microsoft Entra ID. ### Registering a Custom Azure App ID Versus Shared Rclone Credentials By default, rclone connects to Microsoft services using a shared public client ID embedded in the binary. Because thousands of rclone users around the world send requests through that same public ID, Microsoft's global rate limiters often flag requests coming from shared credentials during peak traffic periods. Creating a custom App Registration in the Microsoft Entra ID portal isolates your traffic into an independent quota pool: 1. Log in to the Microsoft Azure portal and open **Microsoft Entra ID**. 2. Select **App registrations** and choose **New registration**. 3. Name the application (for example, `rclone-onedrive-storage`), select **Accounts in any organizational directory and personal Microsoft accounts**, and set the redirect URI to `http://localhost:53682/` (Web). 4. Under **Certificates & secrets**, generate a new client secret and copy its value immediately. 5. Under **API permissions**, add delegated permissions for Microsoft Graph: `Files.Read`, `Files.ReadWrite`, `Files.Read.All`, `Files.ReadWrite.All`, and `offline_access`. 6. Run `rclone config`, edit your existing OneDrive remote, and paste your custom `client_id` and `client_secret` when prompted. Isolating your mount to a private client ID prevents other third-party rclone users from exhausting your API capacity. ### Request Pacing and Directory Cache Tuning Rclone contains an internal pacer that dynamically increases sleep durations when receiving rate-limiting signals. Relying entirely on reactive backoff still generates initial bursts of 429 errors that freeze application threads. Applying proactive request constraints eliminates the traffic spikes that trigger throttling: * **`--tpslimit 3` and `--tpslimit-burst 0`:** Limits the transaction pace to three requests per second with zero burst allowance. Microsoft OneDrive handles continuous streams at this cadence reliably, whereas uncontrolled bursts trigger immediate cooldowns. * **`--dir-cache-time 72h`:** Instructs rclone to maintain directory listings in local RAM for 72 hours. File and folder structures remain cached after the first lookup, allowing navigation and directory listing commands to resolve instantly from memory without contacting Microsoft Graph. * **`--poll-interval 1m`:** OneDrive personal and business remotes support server-side change polling. Rather than rescanning the entire remote tree, rclone queries the Microsoft Graph delta API once a minute to pull down changed items, keeping the directory cache current while consuming minimal requests. * **Restricting recursive file walkers:** Avoid running generic tree traversals like `du -sh /mnt/onedrive` or recursive linters across mounted cloud folders. Each unvisited subfolder requires an independent directory listing API call that depletes your hourly quota allocation. ## Deploying Rclone Mount on Linux as a Managed Systemd Service Running `rclone mount` directly inside an interactive shell session works for short testing runs, but production servers require an automated background daemon. Wrapping rclone in a systemd service unit starts the mount automatically on boot, restarts it if the network drops, and unmounts cleanly during system shutdowns. ### Step 1: Install FUSE and Configure Permissions Before configuring systemd, confirm that the FUSE driver is installed and non-root users have permission to export mount options. Update package repositories and install the FUSE3 package on Ubuntu or Debian: ```bash sudo apt update && sudo apt install -y fuse3 ``` Enable the allow_other option in the FUSE configuration file: ```bash sudo sed -i 's/#user_allow_other/user_allow_other/' /etc/fuse.conf ``` Create the target mount point and assign ownership to the service user: ```bash sudo mkdir -p /mnt/onedrive sudo chown tom:tom /mnt/onedrive ``` ### Step 2: Configure the Service Unit via Systemd Create the systemd service file at `/etc/systemd/system/rclone-onedrive.service` using an automated configuration command: ```bash printf '[%s] Description=Rclone OneDrive Mount Service Documentation=man:rclone(1) After=network-online.target Wants=network-online.target [%s] Type=notify User=tom Group=tom ExecStart=/usr/bin/rclone mount onedrive: /mnt/onedrive \ --config=/home/tom/.config/rclone/rclone.conf \ --vfs-cache-mode full \ --vfs-cache-max-size 50G \ --vfs-cache-max-age 24h \ --vfs-read-chunk-size 64M \ --vfs-read-chunk-size-limit 512M \ --vfs-write-back 5s \ --buffer-size 32M \ --dir-cache-time 72h \ --poll-interval 1m \ --tpslimit 3 \ --tpslimit-burst 0 \ --allow-other \ --umask 022 \ --log-file=/var/log/rclone-onedrive.log \ --log-level NOTICE ExecStop=/bin/fusermount -u /mnt/onedrive Restart=on-failure RestartSec=10s TimeoutStopSec=30s [%s] WantedBy=multi-user.target ' "Unit" "Service" "Install" | sudo tee /etc/systemd/system/rclone-onedrive.service ``` ### Step 3: Enable and Verify the Service Reload the systemd manager configuration, enable the unit to start at boot, and launch the service: ```bash sudo systemctl daemon-reload sudo systemctl enable rclone-onedrive.service sudo systemctl start rclone-onedrive.service ``` Inspect the service status to verify that the FUSE mount initialized successfully: ```bash systemctl status rclone-onedrive.service ``` When the mount status displays active and running, verify directory access using standard file tools: ```bash df -h /mnt/onedrive ls -la /mnt/onedrive ``` When stopping or restarting the service, systemd invokes `fusermount -u` to detach the FUSE mount cleanly. If a running process holds an open file handle, unmounting may block. In emergency troubleshooting scenarios, issuing `fusermount -uz /mnt/onedrive` performs an unmount detachment, allowing systemd to restart the daemon cleanly. ## Architecting Agent Storage: When to Mount Versus Remote Workspace Sync While mounting OneDrive via Rclone provides local filesystem access, relying on FUSE mounts introduces architectural constraints when scaling autonomous AI agents. Understanding the operational tradeoffs helps determine when a local mount is appropriate and when a shared cloud workspace provides a more stable foundation. Autonomous agents inspect code, analyze documentation, and generate deliverables across complex loops. Connecting an agent directly to a local FUSE mount exposes several systemic limitations: 1. **Local disk footprint:** Full VFS caching buffers remote files locally. An agent processing a large collection of design documents or technical archives consumes equivalent local server disk space, creating capacity issues on small cloud instances. 2. **Host binding and isolation:** A FUSE mount is bound to a single physical machine or virtual server. Distributed agents, containerized workers, and hosted LLM environments (such as Claude Code, Codex, or cloud runners) cannot access the local mount without maintaining custom network tunnels. 3. **High latency on cold file reads:** When an agent inspects hundreds of files across a directory tree, each uncached read incurs round-trip HTTP overhead to Microsoft Graph. Even with chunked reads, cumulative network latency delays agent task completion. 4. **Concurrency conflicts:** When multiple agents write to the same mounted directory, local VFS caches operate independently. Two processes writing to the same remote path can overwrite each other's changes without retaining an auditable log of intermediate versions. ``` +-----------------------------------------------------------------------------------------+ | Storage Architecture | +-----------------------------------------------------------------------------------------+ | | | Pattern A: Local FUSE Mount | | (Agent Process) ---> (Local FUSE Mount) ---> (Local Disk VFS Cache) ---> (Graph API) | | - Bound to single host machine | | - Heavy local disk overhead | | - Subject to per-request API throttling | | | | Pattern B: Fast.io Workspace and Remote MCP Access | | (OneDrive Account) ---> (Scheduled Cloud Sync) ---> (Shared Fast.io Workspace) | | | | | (Auto-Indexed Search) | | | | | (Coding Agent or Claude) <--- (Streamable HTTP MCP) <----------+ | | - Zero local disk footprint | | - Semantic and hybrid metadata queries | | - Preserved per-file version history | +-----------------------------------------------------------------------------------------+ ``` ### Storage Approaches for Agent Infrastructure Engineering teams typically choose among three primary storage architectures when building file access for autonomous agents: * **Local SSD and Cloud Block Storage:** Hosting files on local NVMe drives or cloud block storage provides high I/O performance and avoids network rate limits. However, storage remains locked to an individual instance, preventing team members from viewing or modifying files without manual sync pipelines. * **Direct Cloud Storage Mounts (Rclone FUSE):** Exposing OneDrive, Dropbox, or Google Drive via FUSE allows existing scripts to read remote files with zero code changes. This approach is effective for single-server background tasks, but it remains susceptible to Microsoft Graph throttling and lacks native semantic search. * **Intelligent Cloud Workspaces (Fast.io):** Connecting your existing cloud storage to [Fast.io agent storage](/storage-for-agents/) allows files to be indexed and queried through a remote Model Context Protocol (MCP) server without local mount overhead. ### The Fast.io Integration Path Rather than forcing teams to migrate away from existing cloud storage providers, Fast.io works alongside Microsoft OneDrive. Cloud Sync connects to your existing OneDrive folders (one-way or two-way, on a schedule or on demand; never continuous, live, or real-time; SharePoint document libraries are accessed through the OneDrive connector). Once synced into an organization-owned Fast.io workspace: * **Intelligence Mode:** Fast.io automatically indexes incoming files for hybrid Search (combining full-text keyword matching, semantic meaning, and metadata value filters). Rather than downloading entire PDF manuals or datasets across a FUSE mount, agents run targeted search queries that return relevant excerpts with citations. * **Remote MCP Architecture:** Agents connect to Fast.io over Streamable HTTP without running local background daemons. Coding agents (such as Claude Code, Cursor, and terminal agents) connect to `https://mcp.fast.io/mcp/code`, while Claude apps and general agent environments connect to `https://mcp.fast.io/mcp/tools`. Codex connects through the Fastio plugin first, or uses `https://mcp.fast.io/mcp/operations` as a custom MCP server for the Codex IDE extension or when plugins are blocked. Setup instructions are documented in the [Fast.io MCP documentation](https://mcp.fast.io/docs). * **Version History and Coordination:** Every file keeps a comprehensive version history, preventing concurrent agent writes from causing silent data loss. Teams can coordinate multi-agent access using advisory per-file locks (`lock-acquire` on `storage_manage`), and human team members can inspect changes through an append-only audit log. * **Measured Performance:** In multi-provider evaluations, native cloud connectors exhibit significant performance differences under heavy agent workloads. The connector comparison is published at https://fast.io/benchmarks/ where Fastio was measured the fastest and the lowest cost of the providers tested. Every organization runs on a paid subscription, and monthly plans start with a 14-day trial that requires a credit card. Plan specifications and resource allocations are structured across three tiers: | Plan | Monthly Price | Included Seats | Included Storage | Workspaces | Monthly Credits | | :--- | :--- | :--- | :--- | :--- | :--- | | Starter | $9.99/mo | 3 seats | 250 GB | 5 | 100,000 | | Business | $49.99/mo | 10 seats | 5 TB | 50 | 600,000 | | Enterprise | $199.99/mo | 30 seats (expandable up to 200 seats at $1/seat) | 25 TB | 200 | 3,000,000 | Usage beyond plan allocations is billed directly in currency rather than consuming credits: | Resource Dimension | Plan Allowance | Over-Quota Rate | | :--- | :--- | :--- | | Additional Storage | Included up to tier cap | 1.5 cents per GB monthly | | Bandwidth | None; billed by use | 4 cents per GB | | AI Processing Credits | Monthly credit allotment | $10 per 100,000 credits | Details and plan upgrades are available on the [pricing page](/pricing/). ## Troubleshooting Rclone OneDrive Mount Failures and Error Codes Diagnosing rclone mount failures requires isolating whether an error originates from the local Linux FUSE layer, the VFS cache manager, or the Microsoft Graph API backend. The following table outlines the most common error signatures encountered during production deployments alongside their direct remediations: | Error Message or Symptom | Root Cause | Resolution | | :--- | :--- | :--- | | `error 429: throttledRequest` | Exceeded Microsoft Graph transaction rate limits | Add `--tpslimit 3 --tpslimit-burst 0` and configure a custom Azure App Registration. | | `Transport endpoint is not connected` | Rclone daemon process terminated unexpectedly | Run `fusermount -u /mnt/onedrive`, inspect systemd logs with `journalctl -u rclone-onedrive`, and restart the service. | | `directory not empty` | Mount point contains pre-existing local files | Remove local files from the mount directory before starting rclone or designate a clean mount folder. | | `fusermount: option allow_other only allowed if 'user_allow_other' is set` | Security restriction in `/etc/fuse.conf` | Uncomment `user_allow_other` in `/etc/fuse.conf` using root privileges. | | `database disk image is malformed` (SQLite) | Mount running with `--vfs-cache-mode off` or `writes` | Change mount configuration to `--vfs-cache-mode full` to provide sparse-file random write emulation. | | System freezes during recursive `ls` or `find` | Excessive directory metadata requests | Increase `--dir-cache-time` to `72h` and avoid scanning deep folder hierarchies without path filters. | ### Recovering from Stalled Mounts If an rclone process crashes while leaving a hung FUSE mount point behind, standard directory commands like `ls /mnt/onedrive` will freeze. Attempting a standard unmount with `umount /mnt/onedrive` typically fails with a device busy error. To recover without rebooting the server, perform a lazy unmount: ```bash sudo fusermount -uz /mnt/onedrive ``` Confirm whether any orphaned rclone processes remain active in the process table: ```bash pgrep -fl rclone ``` If an unresponsive process persists, terminate it safely: ```bash sudo pkill -9 -f "rclone mount onedrive:" ``` Once detached, verify that the local cache directory has sufficient free disk space before restarting the daemon. If the cache volume ran out of space during a large write operation, rclone may fail to initialize until expired cache files are removed or the `--vfs-cache-max-size` ceiling is adjusted. ## Frequently asked questions ### How do I mount OneDrive using Rclone? To mount Microsoft OneDrive using Rclone, install rclone and fuse3, configure a remote pointing to Microsoft OneDrive using `rclone config`, and execute `rclone mount remote: /path/to/mountpoint --vfs-cache-mode full`. Using full VFS caching allows read-write operations, file seek calls, and local application scripts to function identically to standard local disks. ### What is the best VFS cache mode for Rclone OneDrive? --vfs-cache-mode full is the recommended mode for Microsoft OneDrive. Because cloud object storage APIs do not natively support byte-level random writes, full VFS caching buffers reads and writes to local disk as sparse files. This mode provides compatibility for SQLite databases, file-editing scripts, and AI coding agents that require random read-write access. ### Why is Rclone mount OneDrive slow or getting throttled? Rclone mounts become slow or encounter HTTP 429 throttling errors when directory traversals or file operations exceed Microsoft Graph API request limits. To resolve throttling, configure `--tpslimit 3` with `--tpslimit-burst 0` to pace outbound requests, increase `--dir-cache-time` to 72 hours, and register a dedicated custom Client ID in Microsoft Entra ID to bypass shared public rclone quotas. ### Can multiple AI agents write to the same Rclone OneDrive mount simultaneously? Multiple agents writing to the same Rclone mount simultaneously can cause data corruption or race conditions. Because rclone buffers writes locally before uploading finalized objects, concurrent writes to the same file path will overwrite each other without conflict resolution. For multi-agent workflows, use a shared cloud workspace with per-file version history and advisory locking. ### How do I unmount a stuck Rclone OneDrive mount? If an Rclone mount freezes or displays a transport endpoint not connected error, run `fusermount -uz /path/to/mountpoint` to perform a lazy unmount. This detaches the unresponsive FUSE endpoint immediately and releases hung process handles without requiring a server reboot. ### How does Fast.io Cloud Sync differ from an Rclone OneDrive mount? An Rclone mount exposes OneDrive files as a virtual disk on a single local server using FUSE and local disk caching. Fast.io Cloud Sync connects directly to your OneDrive account on a schedule or on demand, copying files into an intelligent cloud workspace where content is automatically indexed for semantic search and accessible to AI agents via remote MCP endpoints without consuming local disk space. ## Sources - [Rclone Documentation: rclone mount](https://rclone.org/commands/rclone_mount/): Applications requiring random writes or seeking cannot operate on an unbuffered Rclone mount without full or write VFS caching enabled. - [Microsoft Learn: Microsoft Graph Throttling Guidance](https://learn.microsoft.com/en-us/graph/throttling): Microsoft Graph API rate limits vary across request types and can restrict write traffic while continuing to allow read requests. ## About Fast.io Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli. MCP setup is at https://mcp.fast.io/docs: Claude and most MCP clients connect to https://mcp.fast.io/mcp/tools, ChatGPT to https://mcp.fast.io/mcp/operations, and coding agents to https://mcp.fast.io/mcp/code.