Google Drive

GoogleDriveVFS exposes a user’s Drive (My Drive plus shared drives the user can see) as a tree. Setup steps for OAuth credentials live at Google Workspace Credentials.

Node

pnpm add @struktoai/mirage-node

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

const drive = new GoogleDriveVFS({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  refreshToken: process.env.GOOGLE_REFRESH_TOKEN!,
})

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

Browser

pnpm add @struktoai/mirage-browser

import { GoogleDriveVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const drive = new GoogleDriveVFS({
  clientId: GOOGLE_CLIENT_ID,
  clientSecret: GOOGLE_CLIENT_SECRET,
  refreshToken: localStorage.getItem('gdrive.refresh_token')!,
})

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

The browser examples in examples/browser/vfs/gdrive/gdrive_pkce.ts show a full PKCE flow that keeps the secret out of the page.

Config

Field	Description
`timeout` default `DEFAULT_TIMEOUT`	Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
`accessToken` secret	OAuth access token, or a function (sync or async) that returns one. Takes precedence over `clientId` and `refreshToken`.
`clientId`	Google OAuth client ID. Required with `refreshToken` when `accessToken` is unset; mirage then mints and renews access tokens itself.
`clientSecret` secret	Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
`refreshToken` secret	User’s OAuth refresh token. Required with `clientId` when `accessToken` is unset.
`refreshFn` secret	Function that exchanges the refresh token for `{ accessToken, expiresIn }` instead of Google’s token endpoint, so the client secret can stay on a backend. Still needs `clientId` and `refreshToken`.
`apiBase`	One base URL that replaces every Google API host and the OAuth token endpoint, such as a test server. Unset uses Google’s hosts.
`folderId`	Drive folder ID the `gdrive` mount uses as its root instead of My Drive; it may be a folder in a Shared Drive. Other Google mounts ignore it.

Fields marked secret are redacted in snapshots.

Mount mode

read, write and exec. Under write mode the standard write commands (tee, cp, mv, rm, mkdir, sed -i, …) work on regular files and folders; Google-native files (.gdoc.json, .gsheet.json, .gslide.json) are mutated through the gws commands instead. Use MountMode.EXEC if python3 or js should run scripts from the mount. A Shared Drive is writable on the same terms as My Drive: every Drive call carries supportsAllDrives, so what you may change is decided by your role on that drive rather than by the mount, and a role that forbids the change fails with EACCES on that operand.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

VFS Layout

`/<path>`

/<path>
  <folder>/              # the Drive folder hierarchy, mirrored
    <name>.gdoc.json     # Google Docs: the gdocs gdoc.json shape
    <name>.gsheet.json   # Google Sheets: the gsheets gsheet.json shape
    <name>.gslide.json   # Google Slides: the gslides gslide.json shape
    <file>               # PDFs, images and the rest: raw bytes
  <shared-drive>/        # each shared drive you can see

There is no owned/ and shared/ split: this is your full Drive view, including files shared with you that were added to My Drive.
This is a remote mount: prefer targeted reads over full scans. A date-prefixed glob (2026-05-*) becomes a Drive modifiedTime range query.
To act on Drive items by id (create, update, export, permissions), use the gws CLI if installed (gws drive --help).

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

## VFS Layout

### `/<path>`

```text
/<path>
  <folder>/              # the Drive folder hierarchy, mirrored
    <name>.gdoc.json     # Google Docs: the gdocs gdoc.json shape
    <name>.gsheet.json   # Google Sheets: the gsheets gsheet.json shape
    <name>.gslide.json   # Google Slides: the gslides gslide.json shape
    <file>               # PDFs, images and the rest: raw bytes
  <shared-drive>/        # each shared drive you can see
```

- There is no `owned/` and `shared/` split: this is your full Drive
  view, including files shared with you that were added to My Drive.
- This is a remote mount: prefer targeted reads over full scans. A
  date-prefixed glob (`2026-05-*`) becomes a Drive `modifiedTime` range
  query.
- To act on Drive items by id (create, update, export, permissions), use
  the `gws` CLI if installed (`gws drive --help`).

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

Integration

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

Command	On Google Drive
`grep -r`, `rg`	Drive full-text search, for whole words (`-w`, `-x`). It can miss Docs, Sheets and Slides JSON, office files, PDFs, archives, the end of large files, words Drive splits differently (`foo.bar`) and recent writes.
`md5sum`, `sha1sum`, `sha256sum`	The digest Drive keeps; a Docs, Sheets or Slides file is read
`find`, `du`, `ls -R`, `tree`	One recursive listing

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

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​Node

​Browser

​Config

​Mount mode

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration