SharePointVFS mounts SharePoint Online: every site the token can reach
becomes a folder of its document libraries, each holding its real files as raw
bytes. Site and library names are resolved to Microsoft Graph IDs by the
mount, so no drive ID is needed. Set up the tokens as in SharePoint setup.
Install
Configure
tenantHost and siteFilter narrow the sites listed. site and drive
together mount one library as the root, and keyPrefix one folder inside it.
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.SharePoint host, such as
contoso.sharepoint.com; the sharepoint mount lists only the sites whose webUrl is on it. The onedrive mount ignores it.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.Search term passed to Graph’s
/sites?search= to choose which sites the mount lists.Site, by display name or internal name, that scopes the mount to one document library together with
drive. With either unset the mount lists every site as /<site>/<library>/....Folder path inside the scoped library that the mount uses as its root; takes effect only with
site and drive set. .. segments are rejected.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.
An app-only token works, since the mount reaches sites through /sites and
needs no signed-in user. Reads need Sites.Read.All; writes need
Sites.ReadWrite.All. A delegated token reaches only what its user can.
Layout
/<site>/<library>/<path>, with the site’s display name. The first
two levels are sites and libraries; everything below is a real driveItem.
/sharepoint/Engineering/Documents/specs/api.md is the driveItem
/root:/specs/api.md in the Documents library of the Engineering site.
With site: 'Engineering' and drive: 'Documents', those two levels
disappear. Adding keyPrefix: 'team/reports' makes that folder the root, so
/sharepoint/q1.csv is the driveItem /root:/team/reports/q1.csv.
Behavior
- Scoping:
drivetakes effect only withsiteset, andkeyPrefixonly with both...segments inkeyPrefixare rejected. - 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. A token minted for one sovereign cloud is rejected by the others, so a mount on the wrong root fails outright. - 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.
- One drive instead: for a single drive, such as a personal OneDrive or one known library, use OneDrive.
Browser
@struktoai/mirage-browser exports the same SharePointVFS 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
SharePoint 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, within one document library; a directory above a library is read in full. 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 SharePoint 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
VFS Layout
/<path>- An unscoped mount reads
/{site_name}/{library_name}/{path_to_file}.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.