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
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.
OAuth access token, or a function (sync or async) that returns one. Takes precedence over
clientId and refreshToken.Google OAuth client ID. Required with
refreshToken when accessToken is unset; mirage then mints and renews access tokens itself.Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
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.One base URL that replaces every Google API host and the OAuth token endpoint, such as a test server. Unset uses Google’s hosts.
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.Authentication
Credentials come from the first of:accessToken, a token or a function, sync or async, that returns one.clientIdandrefreshToken, withclientSecretunless the client uses PKCE. Mirage trades the refresh token for access tokens on its own, or hands it torefreshFnwhen set, so the secret can stay on a backend.
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.jsonand.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
writemount,tee,cp,mv,rm,mkdir,rmdir,touch,truncateandsed -iwork on regular files and folders.mkdirover an existing name fails withFile exists,mvonto a non-empty directory withDirectory not empty, andcp -rmerges.rmdeletes 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 thegwsCLI, 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.READmakes a mount that cannot write at all.
Browser
The sameGoogleDriveVFS 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-tokenstands for a backend endpoint that returns an access token.- A PKCE OAuth client needs no secret:
clientIdandrefreshTokenalone mount it.examples/browser/vfs/gdrive/gdrive_pkce.tsshows the sign-in flow. refreshFnsends 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 -randrgwith-wor-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 bytesgrepreads, 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: -1in the mount’s"@all"command limit turns the search off and reads every file.md5sum,sha1sumandsha256sum: the digest Drive keeps. A Docs, Sheets or Slides file is read.find,du,ls -Randtree: 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.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>- The full Drive view, folders mirrored, with files shared into My Drive;
there is no
owned/andshared/split. - Changes by id (create, export, permissions) go through the
gws driveCLI.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.