OneDrive

The OneDrive VFS mounts a Microsoft OneDrive (or SharePoint document library) at some prefix such as /onedrive/. 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. Compatible with: personal OneDrive, OneDrive for Business, and SharePoint document libraries (driveItems on Microsoft Graph v1.0). For credential setup (tokens, drive ids, app vs delegated auth), see the OneDrive Setup guide.

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.onedrive import OneDriveVFS, OneDriveConfig

config = OneDriveConfig(
    access_token=os.environ["MS_GRAPH_DRIVE_TOKEN"],
    # Optional:
    # Name at most one drive:
    # drive_id="b!...",        # target a specific drive
    # site_id="contoso.sharepoint.com,...",  # a SharePoint site's default drive
    # group_id="...",          # a Teams / Microsoft 365 group's library
    # user_id="user@contoso.com",  # another user's drive (app-only)
    # graph_base_url="https://graph.microsoft.us/v1.0",  # non-worldwide root
    # key_prefix="Documents/",  # mount a sub-folder as the root
    # timeout=30,
)

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

OneDriveVFS(config) takes an OneDriveConfig object with a Microsoft Graph bearer token and optional drive/site targeting. 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`.
`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.
`drive_id`	Graph drive ID of the drive to mount. Set at most one of `drive_id`, `site_id`, `group_id` and `user_id`; with none the mount uses the signed-in user’s drive.
`site_id`	Graph site ID whose default document library the mount uses.
`group_id`	Microsoft 365 or Teams group ID whose document library the mount uses.
`user_id`	User ID or UPN whose drive the mount uses, under app-only auth.
`key_prefix`	Folder path from the drive root that the mount uses as its root.

Fields marked secret are redacted in snapshots.

Naming the drive

drive_id, site_id, group_id and user_id are four ways of saying which drive the mount is, so set at most one. Setting two raises at config time rather than silently addressing whichever came first, which otherwise surfaces much later as an unexplained 404. Setting none means /me/drive, the signed-in user’s own drive, which requires delegated auth; app-only auth must set one selector and the permissions to read that target.

The service root

Mounts address https://graph.microsoft.com/v1.0 unless graph_base_url says otherwise. Set it to reach anything else: a sovereign cloud, a private endpoint, or a test server. Give the full root including the version segment, for example https://graph.microsoft.us/v1.0. This matters most for the sovereign deployments, which are network-isolated instances rather than regions: a token minted for one is rejected by the others, so a mount pointed at the wrong root fails outright rather than degrading. mirage does not ship a table of their hostnames, since it has no way to verify one; take the root from Microsoft’s national cloud documentation for your tenant. Because the root is read from the config rather than a module constant, two mounts in one process can address different deployments.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

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 `onedrive` 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>` | `onedrive`, write |

## 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 `onedrive` 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.

The OneDrive VFS maps Graph driveItems (path-addressed) to virtual paths under the mount prefix. Folders are real driveItems, so the tree matches what you see in OneDrive. For example, if the drive contains:

Documents/file.txt
Documents/config.json
Reports/q1.csv
Reports/q2.csv

Then mounting at /onedrive/ exposes:

/onedrive/
  Documents/
    file.txt
    config.json
  Reports/
    q1.csv
    q2.csv

Path mapping: virtual /onedrive/Documents/file.txt maps to the driveItem at /root:/Documents/file.txt.

Versioning and Snapshots

OneDrive keeps per-file version history. The VFS exposes it the same way the S3 backend does:

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 OneDrive VFS caches directory listings via IndexCacheStore to reduce repeated Graph calls during traversal.

Example

import asyncio
import os

from mirage import MountMode, Workspace
from mirage.vfs.onedrive import OneDriveVFS, OneDriveConfig

config = OneDriveConfig(
    access_token=os.environ["MS_GRAPH_DRIVE_TOKEN"],
    drive_id=os.environ.get("MS_GRAPH_DRIVE_ID") or None,
)

vfs = OneDriveVFS(config)


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

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

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

    r = await ws.shell("cat /onedrive/note.txt")
    print(await r.stdout_str())

    r = await ws.shell("stat /onedrive/note.txt")
    print(await r.stdout_str())

    r = await ws.shell("tree /onedrive/")
    print(await r.stdout_str())


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

A runnable version lives at examples/python/vfs/onedrive/onedrive.py.

Shell Commands

The OneDrive 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 OneDrive/SharePoint for agents to read and process files
Versioned document workflows: Snapshot and replay exact file states over time
Sandboxed access: Restrict agent operations to a specific drive and sub-folder via key_prefix
FUSE mounting: Expose a OneDrive through a virtual FUSE mount for external tools

Integration

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

Command	On OneDrive
`grep -r`, `rg`	Microsoft Graph search, 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; 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).

Scoping a VFS to a folder

Pass key_prefix: str | None = None to OneDriveConfig to transparently scope every operation to a sub-folder of the drive:

OneDriveVFS(OneDriveConfig(
    access_token=token,
    drive_id=drive_id,
    key_prefix=f"users/{user_id}/",
))

When set, every read/write/list/stat/copy/rename/delete operation is scoped to that sub-folder. Agents see clean paths like /data/notes.md; the underlying driveItem is users/{user_id}/data/notes.md. Useful for multi-tenant systems. Normalization: leading slashes are stripped and a trailing slash is added automatically. Both None and an empty string are treated as “no prefix.”

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

Config Reference

Naming the drive

The service root

VFS.md

Virtual Filesystem

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

Scoping a VFS to a folder

​Config

​Config Reference

​Naming the drive

​The service root

​VFS.md

​Virtual Filesystem

​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

​Scoping a VFS to a folder

Config

Config Reference

Naming the drive

The service root

VFS.md

Virtual Filesystem

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

Scoping a VFS to a folder