Skip to main content
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

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.
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 Gmail API with the 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. ls the 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 that gws gmail read --id and gws gmail reply --message-id take.

Behavior

  • Read only: no command changes the mailbox. Sending, replying, forwarding and triage go through the gws CLI.
  • Recent window: ls of 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.json is 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 same GmailVFS 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.
  • refreshFn sends 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 -r and rg: 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. With walkLimit: -1 in 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>.
Virtual FilesystemVFS 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.
  • ls a date directory for the names rather than building <subject>.
  • A .gmail.json is the email processed by Mirage, not the raw API response: .from, .to, .subject, .date, .body_text, .labels, .attachments[].
  • The sibling directory holds attachments only (cat one for its bytes) and is absent when there are none; grep -r skips its binary files.
  • Triage and other changes go through the gws gmail 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.