> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OneDrive

> Virtualize a OneDrive drive or SharePoint document library from Node or the browser.

`OneDriveVFS` mounts one Microsoft Graph drive: a personal OneDrive, OneDrive
for Business or one SharePoint document library. Its files and folders become
a folder tree of raw bytes. Set up the tokens and drive IDs as in [OneDrive setup](https://docs.mirage.strukto.ai/home/setup/onedrive.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { MountMode, OneDriveVFS, Workspace } from '@struktoai/mirage-node'

const drive = new OneDriveVFS({
  accessToken: process.env.MS_GRAPH_DRIVE_TOKEN!,
})
const ws = new Workspace({ '/onedrive': drive }, { mode: MountMode.WRITE })

const result = await ws.shell("ls /onedrive && find /onedrive -name '*.xlsx'")
console.log(result.stdoutText)
await ws.close()
```

With no drive named, the mount is the signed-in user's own drive. Set one of
`driveId`, `siteId`, `groupId` or `userId` to mount another drive, and
`keyPrefix` to mount one folder.

### Fields

**accessToken** `string | function` *required*

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** `string`

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** `number` (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** `number` (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** `string`

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** `string`

Graph site ID whose default document library the mount uses.

**groupId** `string`

Microsoft 365 or Teams group ID whose document library the mount uses.

**userId** `string`

User ID or UPN whose drive the mount uses, under app-only auth.

**keyPrefix** `string`

Folder path from the drive root that the mount uses as its root.

Fields marked secret are redacted in snapshots.

## Authentication

`accessToken` is a Microsoft Graph bearer token, or a function (sync or async)
that returns one. A function 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.

A delegated token reaches the signed-in user's drive with no drive named. An
app-only token cannot use `/me/drive`, so it must set one of `driveId`,
`siteId`, `groupId` or `userId`, and have the permission to read that target.
Reads need `Files.Read`; writes need `Files.ReadWrite` or a wider write
permission. Other drives and SharePoint may need `Files.Read.All`,
`Files.ReadWrite.All` or a `Sites.*` permission.

## Layout

```text theme={null}
/onedrive/
  Documents/
    file.txt
    config.json
  Reports/
    q1.csv
    q2.csv
```

`/onedrive/Documents/file.txt` is the driveItem at `/root:/Documents/file.txt`.
Folders are real driveItems, so the tree matches what OneDrive shows.

## Behavior

* **Naming the drive:** `driveId`, `siteId`, `groupId` and `userId` are four
  ways to name the drive, so set at most one. Setting two throws at
  construction rather than addressing whichever came first.
* **Folder scope:** `keyPrefix: 'users/42'` mounts only that folder, so
  `/onedrive/data/notes.md` is the driveItem `users/42/data/notes.md`.
  Slashes at either end are ignored.
* **Service root:** mounts address `https://graph.microsoft.com/v1.0` unless
  `graphBaseUrl` names another root, given in full with its version segment,
  such as `https://graph.microsoft.us/v1.0`. Sovereign clouds are separate
  instances, so a token minted for one is rejected by the others and a mount
  on the wrong root fails outright. Take the root from Microsoft's national
  cloud documentation for the tenant.
* **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.

## Browser

`@struktoai/mirage-browser` exports the same `OneDriveVFS` with the same
fields.

```bash theme={null}
npm install @struktoai/mirage-browser
```

```ts theme={null}
import { MountMode, OneDriveVFS, Workspace } from '@struktoai/mirage-browser'

const drive = new OneDriveVFS({ accessToken: () => getMicrosoftGraphToken() })
const ws = new Workspace({ '/onedrive': drive }, { mode: MountMode.READ })
```

* Pass a token function, such as one backed by the page's sign-in library, so
  a `401` fetches a fresh token and retries.

## Integration

OneDrive answers these commands through its own API, so fewer files are read.
See [Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `grep -rw` and `rg -w`: Microsoft Graph search names the files to read,
  for whole words. 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: -1` in the mount's `"@all"`
  [command limit](https://docs.mirage.strukto.ai/home/limits.md#command-output) reads every file instead.
* `grep -r` and `rg` without `-w`: every file is read.
* `find`: one recursive listing.
* `du`: one recursive listing.
* `ls -R` and `tree`: one recursive listing.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with OneDrive mounted at `/<path>`.
`<mode>` is the mount's mode: `read`, `write` or `exec`. The commands shown are
those of a `write` mount.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `onedrive`, `<mode>` |
>
> **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.

> [tab] Raw
>
> ```markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `onedrive`, `<mode>` |
>
> ## 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.
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.