Skip to main content
GoogleDriveVFS mounts a Google Drive account: every folder becomes a directory, every file a file, and Docs, Sheets and Slides read as JSON. My Drive and every Shared Drive the account can see are included. Set up the credentials as in Google Workspace setup.

Install

Configure

folderId mounts one folder instead of the whole Drive. A mount takes MountMode.READ, WRITE or EXEC; EXEC lets python3 and js run scripts from the mount.

Fields

number
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.
string | function
secret
OAuth access token, or a function (sync or async) that returns one. Takes precedence over clientId and refreshToken.
string
Google OAuth client ID. Required with refreshToken when accessToken is unset; mirage then mints and renews access tokens itself.
string
secret
Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
string
secret
User’s OAuth refresh token. Required with clientId when accessToken is unset.
function
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.
string
One base URL that replaces every Google API host and the OAuth token endpoint, such as a test server. Unset uses Google’s hosts.
string
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.

Authentication

Credentials come from the first of:
  1. accessToken, a token or a function, sync or async, that returns one.
  2. clientId and refreshToken, with clientSecret unless the client uses PKCE. Mirage trades the refresh token for access tokens on its own, or hands it to refreshFn when set, so the secret can stay on a backend.
The mount needs the Drive API and the https://www.googleapis.com/auth/drive scope, or drive.readonly for a read-only mount. Drive grants access per item, so a write mount can still hold files the account may not change. A change Drive refuses fails with Permission denied on that operand, and the rest of the mount keeps working.

Layout

  • The root holds My Drive’s folders and files plus one folder per Shared Drive. A Shared Drive whose name clashes gets a [Shared Drive] suffix and, if needed, a number.
  • Regular files (PDFs, images, CSVs) keep their names and read as their bytes.
  • Docs, Sheets and Slides cannot be downloaded as bytes, so they read as the JSON of their own API: .gdoc.json, .gsheet.json and .gslide.json.

Behavior

  • Folder scope: folderId: '1AbCdEf...' makes that folder the mount root. It may sit in My Drive, be shared with the account, sit in a Shared Drive, or be a Shared Drive’s id. A scoped mount shows no other Shared Drive.
  • Writes: on a write mount, tee, cp, mv, rm, mkdir, rmdir, touch, truncate and sed -i work on regular files and folders. mkdir over an existing name fails with File exists, mv onto a non-empty directory with Directory not empty, and cp -r merges. rm deletes for good, not to the trash.
  • Docs, Sheets and Slides: read only as bytes; a write to one fails with Permission denied. Change them with the gws CLI, which also acts on any Drive item by id.
  • Shared Drives: writable on the same terms as My Drive. The account’s role on that drive decides what it may change, and some organizations restrict deleting or moving content out of a drive. MountMode.READ makes a mount that cannot write at all.

Browser

The same GoogleDriveVFS comes from @struktoai/mirage-browser. In a page, an accessToken function fetches a fresh token from a backend, so the client secret never reaches the browser.
  • /api/google-token stands for a backend endpoint that returns an access token.
  • A PKCE OAuth client needs no secret: clientId and refreshToken alone mount it. examples/browser/vfs/gdrive/gdrive_pkce.ts shows the sign-in flow.
  • refreshFn sends each refresh to a backend instead of Google’s token endpoint.

Integration

Drive answers these commands through its own API, so fewer files are read. See Integration.
  • grep -r and rg with -w or -x: Drive full-text search names the files to read. Every file is read when the search fails or finds nothing. Drive searches the text it extracted, not the bytes grep reads, and indexes a write some time after it lands, so it can leave out a file that holds the word: a Docs, Sheets or Slides file (its JSON keys and ids), an office file, PDF or archive, the end of a large file, or a word Drive splits differently (foo.bar). walkLimit: -1 in the mount’s "@all" command limit turns the search off and reads every file.
  • md5sum, sha1sum and sha256sum: the digest Drive keeps. A Docs, Sheets or Slides file is read.
  • find, du, ls -R and tree: one recursive listing.

VFS.md

The VFS.md an agent reads with Google Drive mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemVFS Layout/<path>
  • The full Drive view, folders mirrored, with files shared into My Drive; there is no owned/ and shared/ split.
  • Changes by id (create, export, permissions) go through the gws drive CLI.
Supported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.