OneDrive

OneDriveVFS exposes one Microsoft Graph drive as a read-write filesystem. It uses the same browser-safe core in the Node and browser packages.

import { MountMode, OneDriveVFS, Workspace } from '@struktoai/mirage-node'

const drive = new OneDriveVFS({
  accessToken: () => getMicrosoftGraphToken(),
  // Name at most one drive; none means /me/drive.
  // driveId: '...',       // explicit Graph drive ID
  // siteId: '...',        // a SharePoint site's default drive
  // groupId: '...',       // a Teams / Microsoft 365 group's library
  // userId: '...',        // another user's drive (app-only auth)
  // graphBaseUrl: 'https://graph.microsoft.us/v1.0',  // non-worldwide root
  // keyPrefix: 'Reports', // optional folder-scoped mount
})

const ws = new Workspace({ '/onedrive': drive }, { mode: MountMode.WRITE })
await ws.shell('ls /onedrive/')

Use @struktoai/mirage-browser for the same API in a browser. An access-token callback is recommended so a 401 can refresh the token and retry once.

Field	Description
`accessToken` 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`.
`graphBaseUrl`	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 `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.
`maxRetries` 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.
`driveId`	Graph drive ID of the drive to mount. Set at most one of `driveId`, `siteId`, `groupId` and `userId`; with none the mount uses the signed-in user’s drive.
`siteId`	Graph site ID whose default document library the mount uses.
`groupId`	Microsoft 365 or Teams group ID whose document library the mount uses.
`userId`	User ID or UPN whose drive the mount uses, under app-only auth.
`keyPrefix`	Folder path from the drive root that the mount uses as its root.

Fields marked secret are redacted in snapshots. driveId, siteId, groupId and userId are four ways of saying which drive the mount is, so set at most one: setting two throws at construction rather than silently addressing whichever came first. Setting none means /me/drive, which is the only form an app-only token cannot use. Mounts address https://graph.microsoft.com/v1.0 unless graphBaseUrl says otherwise. Set it to reach anything else: a sovereign cloud, a private endpoint, or a test server, given in full including the version segment. The sovereign deployments are network-isolated instances rather than regions, so a token minted for one is rejected by the others and a mount pointed at the wrong root fails outright. mirage ships no table of their hostnames, having no way to verify one; take the root from Microsoft’s national cloud documentation for your tenant.

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 to list every command, and 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` to list every command, and `man <cmd>` or `<cmd> --help` for one command's usage.

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

The Python OneDrive docs list when each search answers and what it can miss.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration