GDocsVFS mounts the Google Docs an account can see: each document becomes a
.gdoc.json file holding the Docs API’s JSON, split into the documents it owns
and those shared with it. Set up the credentials as in Google Workspace setup.
Install
Configure
accessToken replaces the client and refresh token with a token or a
function that returns one. A MountMode.WRITE mount also allows mv and rm.
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.
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/documents scope, and the Drive API with the
https://www.googleapis.com/auth/drive scope, since the listing comes from
Drive. A read-only mount can use the readonly variants of both scopes.
Layout
owned/holds the documents the account owns, shared or not;shared/holds those others shared with it.- A file is named
<YYYY-MM-DD>_<title>__<document-id>.gdoc.json. The date is the last modified day and is left out when Drive gives none. - A file holds the Docs API’s JSON for the document, with every tab.
Behavior
- Shared Drives: a document in a Shared Drive has no owner, so it is
listed under
shared/, as on thegdrivemount. - Date globs: a glob on the date prefix, such as
2026-05-*, asks Drive only for the documents modified on those days. - Incomplete listings: Drive may skip part of the account’s files and say
so. The short listing is still shown, and the next
lslists again. - Rename: on a
writemount,mvto a new name in the same folder changes the title. The date and the id must stay, and the title is spelled as the listing spells it (spaces become_). - Delete: on a
writemount,rmdeletes the document for good, not to the trash.owned/andshared/cannot be removed. - Edits: writing text into a document, and raw API calls, go through the
gwsCLI.
Browser
The sameGDocsVFS 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/gdocs/gdocs_pkce.tsshows the sign-in flow. refreshFnsends each refresh to a backend instead of Google’s token endpoint.
Integration
Google Docs answers these commands through its own API, so fewer files are read. See Integration.grep -randrgwith-w: Drive full-text search names the documents to read. Every one is read when the search fails or finds nothing, and when the word may be in any document’s JSON whatever the text says: a word with a digit, a Docs API name or value (paragraph,NORMAL_TEXT), or a word every document carries (https,arial). Drive indexes a write some time after it lands and searches the document’s text, so it can leave out one whose JSON holds the word only in another value (a font, a link or image address, a tab title, an id) or only inside a word that styling splits (snowin bold insidesnowman).walkLimit: -1in the mount’s"@all"command limit turns the search off and reads every file.
VFS.md
The VFS.md an agent reads with Google Docs 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><YYYY-MM-DD>is the file’smodifiedTime, so a date glob such as2026-05-*narrows the query;<title>turns spaces and characters outside[A-Za-z0-9_.-]into_, at most 100 characters.shared/holds docs others shared; docs owned and shared out stay inowned/.- A file is the Docs API
documents.getresponse with every tab under.tabs[].documentTab, nested through.childTabs; there is no top-level.body. All text:[.. | .textRun? // empty | .content] | add. - On a
writepath,rma file to delete it from Drive, ormvit to a new<title>with the same folder, date and id to rename it.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.