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 tokens as in SharePoint setup.
Install
Configure
tenant_host and site_filter narrow the sites listed. site and drive
together mount one library as the root, and key_prefix one folder inside it.
Fields
Microsoft Graph bearer token, or a callable 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. Unset searches *.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
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.
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 key_prefix="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, andkey_prefixonly with both...segments inkey_prefixare rejected. - Service root: mounts address
https://graph.microsoft.com/v1.0unlessgraph_base_urlnames 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.
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.