SharePoint

The SharePoint VFS mounts Microsoft SharePoint Online at some prefix such as /sharepoint/. Unlike the single-drive OneDrive VFS, it exposes the full enterprise topology: many sites, each with many document libraries. Site and drive names are resolved to Microsoft Graph ids automatically, so you mount once and browse everything you have access to. All operations involve network I/O to Microsoft Graph. Files are served as raw bytes (no Office filetype conversion). Uses aiohttp for async Graph access. For credential setup (tokens, app vs delegated auth, permissions), see the SharePoint Setup guide.

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.sharepoint import SharePointVFS, SharePointConfig

config = SharePointConfig(
    access_token=os.environ["MS_GRAPH_DRIVE_TOKEN"],
    # Optional:
    # tenant_host="contoso.sharepoint.com",  # restrict to one tenant host
    # site_filter="Engineering",             # narrow the site search
    # site="Engineering",                    # mount one site
    # drive="Documents",                     # mount one library
    # key_prefix="team/reports",             # mount one folder subtree
    # graph_base_url="https://graph.microsoft.us/v1.0",  # non-worldwide root
    # timeout=30,
    # max_retries=5,
)

vfs = SharePointVFS(config)
ws = Workspace({"/sharepoint": vfs}, mode=MountMode.WRITE)

SharePointVFS(config) takes a SharePointConfig object with a Microsoft Graph bearer token. No drive id is required: the VFS discovers sites and drives for you. Both READ and WRITE modes are supported.

Config Reference

Field	Description
`access_token` required, secret	Microsoft Graph bearer token, or a callable that returns one; it is called for each request and again after a `401`.
`tenant_host`	SharePoint host, such as `contoso.sharepoint.com`; the `sharepoint` mount lists only the sites whose `webUrl` is on it. The `onedrive` mount ignores it.
`graph_base_url`	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`.
`timeout` default `30`	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.
`max_retries` 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.
`site_filter`	Search term passed to Graph’s `/sites?search=` to choose which sites the mount lists. Unset searches `*`.
`site`	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>/...`.
`drive`	Document library in `site` that the mount uses as its root; takes effect only with `site` set.
`key_prefix`	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. access_token accepts either a static string or a Callable[[], str] provider. With a callable, the VFS refreshes the token on 401, so long-running mounts survive token expiry. graph_base_url selects the Graph deployment, and means the same here as for OneDrive: see The service root.

VFS.md

The VFS.md an agent reads with SharePoint mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`sharepoint`, write

`/<path>` layout

/<path>
  SharePoint Enterprise document libraries. Multi-site, multi-drive discovery.
  Unscoped mounts use: /{site_name}/{library_name}/{path_to_file}
  Unscoped level 0 (ls /): lists all accessible SharePoint sites.
  Unscoped level 1 (ls /site/): lists document libraries (drives) in that site.
  Unscoped level 2+ (ls /site/lib/...): lists files and folders in the drive.
  IMPORTANT: This is a remote mount. Prefer targeted reads (grep, head) over full scans. Avoid cat on large files without piping to head/tail.
  File versions are retained, snapshots pin and read prior versions.

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Almost all Unix commands. `grep -r` and `rg` with `-w` ask `sharepoint` which files may match.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Without `-w`, `grep -r` and `rg` read every file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `sharepoint`, write |

## `/<path>` layout

```text
/<path>
  SharePoint Enterprise document libraries. Multi-site, multi-drive discovery.
  Unscoped mounts use: /{site_name}/{library_name}/{path_to_file}
  Unscoped level 0 (ls /): lists all accessible SharePoint sites.
  Unscoped level 1 (ls /site/): lists document libraries (drives) in that site.
  Unscoped level 2+ (ls /site/lib/...): lists files and folders in the drive.
  IMPORTANT: This is a remote mount. Prefer targeted reads (grep, head) over full scans. Avoid cat on large files without piping to head/tail.
  File versions are retained, snapshots pin and read prior versions.
```

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Almost all Unix commands. `grep -r` and `rg` with `-w` ask `sharepoint` which files may match. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Without `-w`, `grep -r` and `rg` read every file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

SharePoint paths follow the structure /{site}/{library}/{path}. The first two levels are virtual (sites and drives), and everything below is a real Graph driveItem.

Level 0 (/sharepoint/): lists all accessible sites
Level 1 (/sharepoint/{site}/): lists document libraries (drives) in that site
Level 2+ (/sharepoint/{site}/{library}/...): lists files and folders

For example:

/sharepoint/
  Engineering/
    Documents/
      spec.md
      deck.pptx
    Reports/
      q1.csv
  Marketing/
    Shared Documents/
      brand.pdf

Path mapping: virtual /sharepoint/Engineering/Documents/spec.md resolves the site Engineering to a site id, the library Documents to a drive id, then reads the driveItem at /root:/spec.md. When site and drive are configured, those two namespace levels disappear. Adding key_prefix="team/reports" makes that folder the mount root, so virtual /sharepoint/q1.csv resolves to the driveItem at /root:/team/reports/q1.csv.

Versioning and Snapshots

SharePoint keeps per-file version history. The VFS exposes it the same way the OneDrive and S3 backends do:

Fingerprint is the driveItem cTag, so normal reads and stat reflect the current content without extra Graph calls.
Snapshots pin each file the agent read to its driveItem version id. Replaying a snapshot reads /versions/{id}/content, giving the exact bytes captured at snapshot time. A file the agent wrote carries no version and is not checked on replay.

Cache

The SharePoint VFS caches site, drive, and directory listings via IndexCacheStore to reduce repeated Graph calls during traversal.

Example

import asyncio
import os

from mirage import MountMode, Workspace
from mirage.vfs.sharepoint import SharePointVFS, SharePointConfig

config = SharePointConfig(access_token=os.environ["MS_GRAPH_DRIVE_TOKEN"])
vfs = SharePointVFS(config)


async def main() -> None:
    ws = Workspace({"/sharepoint/": vfs}, mode=MountMode.WRITE)

    # list sites, then drives in the first site
    r = await ws.shell("ls /sharepoint/")
    print(await r.stdout_str())

    r = await ws.shell("ls /sharepoint/Engineering/")
    print(await r.stdout_str())

    await ws.shell(
        "echo 'hello from mirage' > /sharepoint/Engineering/Documents/note.txt")

    r = await ws.shell("cat /sharepoint/Engineering/Documents/note.txt")
    print(await r.stdout_str())

    r = await ws.shell("tree /sharepoint/Engineering/Documents/")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

Runnable versions live at examples/python/vfs/sharepoint/sharepoint.py (command matrix) and examples/python/vfs/sharepoint/sharepoint_vfs.py (an in-process ws.shell() run that writes a Markdown report).

Shell Commands

The SharePoint VFS supports the full set of shell commands since it operates on real file content (text, binary, JSON, CSV, etc.). Large files benefit from range reads to avoid downloading entire items.

Read Commands

Command	Notes
`cat`	Read file content
`head` / `tail`	First/last N lines
`grep` / `rg`	Pattern search (file or directory level)
`jq`	Query JSON fields
`wc`	Line/word/byte counts
`stat`	File metadata (name, size, type, modified)
`find`	Recursive search with `-name`, `-maxdepth`
`tree`	Directory tree view
`nl`	Number lines
`du`	Disk usage summary
`file`	Detect file type
`strings`	Extract printable strings from binary
`xxd`	Hex dump
`md5`	MD5 checksum
`sha256sum`	SHA-256 checksum

File Operations

Command	Notes
`cp`	Copy files
`mv`	Move/rename files
`rm`	Remove files
`mkdir`	Create directories
`touch`	Create empty file or update timestamp
`tee`	Write stdin to file and stdout

Path Utilities

Command	Notes
`basename`	Strip directory from path
`dirname`	Strip filename from path
`realpath`	Resolve path
`ls`	List directory contents

Use Cases

AI agents accessing org documents: Mount enterprise SharePoint for agents to read and process files across many sites
Multi-site discovery: Browse every accessible site and library from a single mount, no drive ids to manage
Versioned document workflows: Snapshot and replay exact file states over time
FUSE mounting: Expose SharePoint through a virtual FUSE mount for external tools

Integration

What SharePoint answers through its own API, so fewer files are read. Integration explains each command.

Command	On SharePoint
`grep -r`, `rg`	Microsoft Graph search within one document library, for whole words. It can miss Office files, PDFs, archives, the end of large files, words Graph splits differently (`foo.bar`) and recent writes.
`find`, `du`, `ls -R`, `tree`	One recursive listing

grep -rw and rg -w read only the files Microsoft Graph search names, within one document library (a directory above one is read in full); every file is read when the search fails or finds nothing. walk_limit: -1 in the mount’s "@all" command limit reads every file instead, since Graph searches the text it extracted, not the bytes grep reads, and indexes a write some time after it lands, so a file that holds the word can be left out: an office file, PDF or archive, the end of a large file, or a word Graph splits differently (foo.bar).

SharePoint vs OneDrive

Both backends talk to Microsoft Graph driveItems and behave identically below the drive level. Choose by topology:

Use OneDrive for a single drive (personal OneDrive, OneDrive for Business, or one targeted SharePoint library via drive_id / site_id).
Use SharePoint for enterprise scenarios with many sites and libraries that you want to discover and traverse without knowing drive ids up front.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

Config Reference

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Versioning and Snapshots

Cache

Example

Shell Commands

Read Commands

File Operations

Path Utilities

Use Cases

Integration

SharePoint vs OneDrive

​Config

​Config Reference

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Versioning and Snapshots

​Cache

​Example

​Shell Commands

​Read Commands

​File Operations

​Path Utilities

​Use Cases

​Integration

​SharePoint vs OneDrive

Config

Config Reference

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Versioning and Snapshots

Cache

Example

Shell Commands

Read Commands

File Operations

Path Utilities

Use Cases

Integration

SharePoint vs OneDrive