Skip to main content
OneDriveVFS mounts one Microsoft Graph drive: a personal OneDrive, OneDrive for Business or one SharePoint document library. Its files and folders become a folder tree of raw bytes. Set up tokens and drive IDs as in OneDrive setup.

Install

Configure

With no drive named, the mount is the signed-in user’s own drive. Set one of drive_id, site_id, group_id or user_id to mount another drive, and key_prefix to mount one folder.

Fields

str | callable
required
secret
Microsoft Graph bearer token, or a callable that returns one; it is called for each request and again after a 401.
str
Full Graph service root, version segment included, for any deployment but the worldwide one: a sovereign cloud, a private endpoint or a test server. Unset uses https://graph.microsoft.com/v1.0.
float
default:"30"
Seconds a Graph request may wait to connect, or between two reads of its answer, before it fails; also how long a server-side copy is polled before it fails as unconfirmed.
int
default:"5"
Times a request is retried after a 429, 503 or 504 response. Each retry waits what Retry-After asks or an exponential backoff, at most 30 seconds.
str
Graph drive ID of the drive to mount. Set at most one of drive_id, site_id, group_id and user_id; with none the mount uses the signed-in user’s drive.
str
Graph site ID whose default document library the mount uses.
str
Microsoft 365 or Teams group ID whose document library the mount uses.
str
User ID or UPN whose drive the mount uses, under app-only auth.
str
Folder path from the drive root that the mount uses as its root.
Fields marked secret are redacted in snapshots.

Authentication

access_token is a Microsoft Graph bearer token, or a callable that returns one. A callable is called for each request and again after a 401, so a long-running mount outlives one token; a plain string lasts about an hour. A delegated token reaches the signed-in user’s drive with no drive named. An app-only token cannot use /me/drive, so it must set one of drive_id, site_id, group_id or user_id, and have the permission to read that target. Reads need Files.Read; writes need Files.ReadWrite or a wider write permission. Other drives and SharePoint may need Files.Read.All, Files.ReadWrite.All or a Sites.* permission.

Layout

/onedrive/Documents/file.txt is the driveItem at /root:/Documents/file.txt. Folders are real driveItems, so the tree matches what OneDrive shows.

Behavior

  • Naming the drive: drive_id, site_id, group_id and user_id are four ways to name the drive, so set at most one. Setting two raises at config time rather than addressing whichever came first.
  • Folder scope: key_prefix="users/42" mounts only that folder, so /onedrive/data/notes.md is the driveItem users/42/data/notes.md. Slashes at either end are ignored.
  • Service root: mounts address https://graph.microsoft.com/v1.0 unless graph_base_url names another root, given in full with its version segment, such as https://graph.microsoft.us/v1.0. Sovereign clouds are separate instances, so a token minted for one is rejected by the others and a mount on the wrong root fails outright. Take the root from Microsoft’s national cloud documentation for the tenant; two mounts in one process can use different roots.
  • Raw bytes: Office files stay as they are stored, with no conversion.
  • Snapshots: a snapshot pins each file the agent read to its version, and replaying it reads those exact bytes. A file the agent wrote carries no version and is not checked on replay. Old versions read only while the library keeps them; an admin can cap or turn off versioning.

Integration

OneDrive answers these commands through its own API, so fewer files are read. See Integration.
  • grep -rw and rg -w: Microsoft Graph search names the files to read, for whole words. Every file is read when the search fails or finds nothing. Graph searches the text it extracted, not the bytes, and indexes a write some time after it lands, so it can miss Office files, PDFs, archives, the end of a large file, a word Graph splits differently (foo.bar) and recent writes. walk_limit: -1 in the mount’s "@all" command limit reads every file instead.
  • grep -r and rg without -w: every file is read.
  • find: one recursive listing.
  • du: one recursive listing.
  • ls -R and tree: one recursive listing.

VFS.md

The VFS.md an agent reads with OneDrive mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemSupported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.