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 the 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 driveId, siteId, groupId or userId to mount another drive, and keyPrefix to mount one folder.

Fields

string | function
required
secret
Microsoft Graph bearer token, or a function (sync or async) that returns one; it is called for each request and again after a 401.
string
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.
number
default:"DEFAULT_TIMEOUT"
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.
number
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.
string
Graph drive ID of the drive to mount. Set at most one of driveId, siteId, groupId and userId; with none the mount uses the signed-in user’s drive.
string
Graph site ID whose default document library the mount uses.
string
Microsoft 365 or Teams group ID whose document library the mount uses.
string
User ID or UPN whose drive the mount uses, under app-only auth.
string
Folder path from the drive root that the mount uses as its root.
Fields marked secret are redacted in snapshots.

Authentication

accessToken is a Microsoft Graph bearer token, or a function (sync or async) that returns one. A function 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 driveId, siteId, groupId or userId, 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: driveId, siteId, groupId and userId are four ways to name the drive, so set at most one. Setting two throws at construction rather than addressing whichever came first.
  • Folder scope: keyPrefix: '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 graphBaseUrl 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.
  • 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.

Browser

@struktoai/mirage-browser exports the same OneDriveVFS with the same fields.
  • Pass a token function, such as one backed by the page’s sign-in library, so a 401 fetches a fresh token and retries.

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.