GmailVFS mounts a Gmail account read only: each label becomes a folder of
days, each message a .gmail.json file and its attachments a folder beside
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.
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/gmail.modify scope, which the gws gmail
commands also use, or gmail.readonly for reading alone.
Layout
- System labels are named by their label ID (
INBOX,SENT,STARRED); user labels by their name. - Inside a label, one folder per day, the date each message was received.
- A message file is named
<subject>__<message-id>.gmail.json, the subject sanitized and cut short when needed.lsthe day rather than build the name. - A message with attachments has a folder of the same name without
.gmail.json, holding the decoded files. - The part after
__is the message id thatgws gmail read --idandgws gmail reply --message-idtake.
Behavior
- Read only: no command changes the mailbox. Sending, replying,
forwarding and triage go through the
gwsCLI. - Recent window:
lsof a label lists the days of its 50 most recent messages. A glob over the day names (ls /gmail/INBOX/2026-03-*) or a day folder named directly reaches older days. - Message JSON: a
.gmail.jsonis shaped by Mirage, not the raw Gmail API answer: sender, recipients, subject, date, the decoded plain-text body, labels and the attachment list.
Browser
The sameGmailVFS 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. refreshFnsends each refresh to a backend instead of Google’s token endpoint.
Integration
Gmail answers these commands from what its listing already fetched, so fewer messages are read. See Integration.grep -randrg: listing a label fetches its messages in full, and the listing keeps each message’s text. Only the messages whose text holds the pattern’s text, in any case, are read, and the output is what reading every message prints. Gmail’s own search is not used, since it reads a message’s HTML part and can miss a word of the plain-text body. Attachments are always read, and so is every message for a text that is not ASCII or that may be part of the labels field (inbox,STARRED,Label_1,abel), since labels change after the listing. WithwalkLimit: -1in the mount’s"@all"command limit, the listing keeps no text and every message is read.
VFS.md
The VFS.md an agent reads with Gmail mounted at/<path>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path><label>is a Gmail label (INBOX,SENT,STARRED, … or a user label);<yyyy-mm-dd>is the received date, and listing one queries only that day.lsa date directory for the names rather than building<subject>.- A
.gmail.jsonis the email processed by Mirage, not the raw API response:.from,.to,.subject,.date,.body_text,.labels,.attachments[]. - The sibling directory holds attachments only (
catone for its bytes) and is absent when there are none;grep -rskips its binary files. - Triage and other changes go through the
gws gmailCLI.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.