Skip to main content
The SharePoint resource mounts Microsoft SharePoint Online at some prefix such as /sharepoint/. Unlike the single-drive OneDrive resource, 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.resource.sharepoint import SharePointResource, 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
    # timeout=30,
    # max_retries=5,
)

resource = SharePointResource(config)
ws = Workspace({"/sharepoint": resource}, mode=MountMode.WRITE)
SharePointResource(config) takes a SharePointConfig object with a Microsoft Graph bearer token. No drive id is required: the resource discovers sites and drives for you. Both READ and WRITE modes are supported.

Config Reference

FieldRequiredDescription
access_tokenYesMicrosoft Graph OAuth2 bearer token (string or callable provider)
tenant_hostNoRestrict resolution to a single SharePoint host
site_filterNoSearch term passed to /sites?search= to narrow discovery
timeoutNoRequest timeout in seconds (default 30)
max_retriesNoMax retries on 429/5xx with backoff (default 5)
access_token accepts either a static string or a Callable[[], str] provider. With a callable, the resource refreshes the token on 401, so long-running mounts survive token expiry.

Filesystem Layout

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.

Versioning and Snapshots

SharePoint keeps per-file version history. The resource 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 path to a Graph driveItem version id. Replaying a snapshot reads /versions/{id}/content, giving time-travel to the exact bytes captured at snapshot time.
  • Restore writes a previous version back as the current one.
This makes the SharePoint resource SUPPORTS_SNAPSHOT = True.

Cache

The SharePoint resource 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.resource.sharepoint import SharePointResource, SharePointConfig

config = SharePointConfig(access_token=os.environ["MS_GRAPH_DRIVE_TOKEN"])
resource = SharePointResource(config)


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

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

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

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

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

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


if __name__ == "__main__":
    asyncio.run(main())
Runnable versions live at examples/python/sharepoint/sharepoint.py (command matrix) and examples/python/sharepoint/sharepoint_vfs.py (FUSE mount).

Shell Commands

The SharePoint resource 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

CommandNotes
catRead file content
head / tailFirst/last N lines
grep / rgPattern search (file or directory level)
jqQuery JSON fields
wcLine/word/byte counts
statFile metadata (name, size, type, modified)
findRecursive search with -name, -maxdepth
treeDirectory tree view
nlNumber lines
duDisk usage summary
fileDetect file type
stringsExtract printable strings from binary
xxdHex dump
md5MD5 checksum
sha256sumSHA-256 checksum

File Operations

CommandNotes
cpCopy files
mvMove/rename files
rmRemove files
mkdirCreate directories
touchCreate empty file or update timestamp
teeWrite stdin to file and stdout

Path Utilities

CommandNotes
basenameStrip directory from path
dirnameStrip filename from path
realpathResolve path
lsList 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

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.