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
driveId, siteId, groupId or userId to mount another drive, and
keyPrefix to mount one folder.
Fields
Microsoft Graph bearer token, or a function (sync or async) that returns one; it is called for each request and again after a
401.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.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.
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.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.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,groupIdanduserIdare 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.mdis the driveItemusers/42/data/notes.md. Slashes at either end are ignored. - Service root: mounts address
https://graph.microsoft.com/v1.0unlessgraphBaseUrlnames another root, given in full with its version segment, such ashttps://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
401fetches a fresh token and retries.
Integration
OneDrive answers these commands through its own API, so fewer files are read. See Integration.grep -rwandrg -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: -1in the mount’s"@all"command limit reads every file instead.grep -randrgwithout-w: every file is read.find: one recursive listing.du: one recursive listing.ls -Randtree: 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.
- Rendered
- Raw
Virtual Filesystem
Supported 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.