Skip to main content
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

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
SharePoint host, such as contoso.sharepoint.com; the sharepoint mount lists only the sites whose webUrl is on it. The onedrive mount ignores it.
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
default:"'*'"
Search term passed to Graph’s /sites?search= to choose which sites the mount lists.
string
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>/....
string
Document library in site that the mount uses as its root; takes effect only with site set.
string
Folder path inside the scoped library that the mount uses as its root; takes effect only with site and drive set. .. segments are rejected.
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. 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

Paths read /<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: drive takes effect only with site set, and keyPrefix only with both. .. segments in keyPrefix are rejected.
  • 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. 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 401 fetches a fresh token and retries.

Integration

SharePoint 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, 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: -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 SharePoint mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemVFS Layout/<path>
  • An unscoped mount reads /{site_name}/{library_name}/{path_to_file}.
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.