Gmail

GmailVFS browses labels, messages, and attachments via the Gmail API. Both runtimes share the same OAuth config: a Google Cloud clientId / clientSecret plus a long-lived refreshToken for the user. Setup steps live at Google Workspace Credentials.

Node

pnpm add @struktoai/mirage-node

import { GmailVFS, MountMode, Workspace } from '@struktoai/mirage-node'

const gmail = new GmailVFS({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  refreshToken: process.env.GOOGLE_REFRESH_TOKEN!,
})

const ws = new Workspace({ '/mail': gmail }, { mode: MountMode.READ })
await ws.shell('ls /mail/INBOX/')

Browser

pnpm add @struktoai/mirage-browser

import { GmailVFS, MountMode, Workspace } from '@struktoai/mirage-browser'

const gmail = new GmailVFS({
  clientId: GOOGLE_CLIENT_ID,
  clientSecret: GOOGLE_CLIENT_SECRET,
  refreshToken: localStorage.getItem('gmail.refresh_token')!,
})

const ws = new Workspace({ '/mail': gmail }, { mode: MountMode.READ })

For OAuth in a browser, prefer PKCE so secrets stay off the page; the Google setup guide shows the flow.

Config

Field	Description
`timeout` 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.
`accessToken` secret	OAuth access token, or a function (sync or async) that returns one. Takes precedence over `clientId` and `refreshToken`.
`clientId`	Google OAuth client ID. Required with `refreshToken` when `accessToken` is unset; mirage then mints and renews access tokens itself.
`clientSecret` secret	Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
`refreshToken` secret	User’s OAuth refresh token. Required with `clientId` when `accessToken` is unset.
`refreshFn` 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`.
`apiBase`	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.

VFS.md

The VFS.md an agent reads with Gmail mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`gmail`, read

VFS Layout

`/<path>`

/<path>
  <label>/
    <yyyy-mm-dd>/
      <subject>__<message-id>.gmail.json   # the email, body included
      <subject>__<message-id>/             # its attachments, if any
        <attachment-filename>

<label> is a Gmail label: INBOX, SENT, DRAFT, IMPORTANT, STARRED, TRASH, SPAM or any user label.
<yyyy-mm-dd> is the date the message was received. Listing one (ls /<path>/INBOX/2026-05-03/) pushes after:/before: into the Gmail query, much cheaper than scanning the whole label.
<subject> is sanitized: ls the date directory rather than construct it. <message-id> is the Gmail message id.
The email body is in the .gmail.json file; read it with cat, head or jq, keeping the suffix. The sibling directory, the same name without the extension, holds attachments only: cat one to download its bytes. grep -r over a date directory skips these binary files.
A grep or rg hit names the .gmail.json file, not the attachments directory. To list a message’s attachments, ls its path with .gmail.json stripped; ENOENT means it has none: ls /<path>/INBOX/2026-05-03/<subject>__<message-id>/

A .gmail.json is processed by Mirage, not the raw Gmail API response:

{
  "id": "...",
  "thread_id": "...",
  "from":    { "name": "...", "email": "..." },
  "to":      [ { "name": "...", "email": "..." } ],
  "cc":      [ ... ],
  "subject": "...",
  "date":    "Mon, 3 May 2026 10:00:00 -0700",
  "body_text": "decoded plain-text body",
  "snippet":   "first ~200 chars from Gmail",
  "labels":  [ "INBOX", "IMPORTANT", ... ],
  "attachments": [
    { "id": "...", "filename": "invoice.pdf",
      "mime_type": "application/pdf", "size": 12345 }
  ]
}

Useful jq paths:

.subject
.from.email
.body_text
.labels[]
.attachments[] | .filename

To act on messages (read by id, triage, raw API calls), use the gws CLI if installed (gws gmail --help).

Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

Path	Supported
`/<path>`	Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `gmail` which files may match.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Read only: no command changes files. `gmail` answers only for `//*.gmail.json`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused.

Run man <cmd> or <cmd> --help for one command’s usage.

---
name: workspace-filesystem
description: The virtual filesystem layout of this workspace.
---

# Virtual Filesystem

| Path | Description |
| --- | --- |
| `/<path>` | `gmail`, read |

## VFS Layout

### `/<path>`

```text
/<path>
  <label>/
    <yyyy-mm-dd>/
      <subject>__<message-id>.gmail.json   # the email, body included
      <subject>__<message-id>/             # its attachments, if any
        <attachment-filename>
```

- `<label>` is a Gmail label: `INBOX`, `SENT`, `DRAFT`, `IMPORTANT`,
  `STARRED`, `TRASH`, `SPAM` or any user label.
- `<yyyy-mm-dd>` is the date the message was received. Listing one
  (`ls /<path>/INBOX/2026-05-03/`) pushes `after:`/`before:` into the
  Gmail query, much cheaper than scanning the whole label.
- `<subject>` is sanitized: `ls` the date directory rather than
  construct it. `<message-id>` is the Gmail message id.
- The email body is in the `.gmail.json` file; read it with `cat`,
  `head` or `jq`, keeping the suffix. The sibling directory, the same
  name without the extension, holds attachments only: `cat` one to
  download its bytes. `grep -r` over a date directory skips these binary
  files.
- A `grep` or `rg` hit names the `.gmail.json` file, not the attachments
  directory. To list a message's attachments, `ls` its path with
  `.gmail.json` stripped; `ENOENT` means it has none:
  `ls /<path>/INBOX/2026-05-03/<subject>__<message-id>/`

A `.gmail.json` is processed by Mirage, not the raw Gmail API response:

```jsonc
{
  "id": "...",
  "thread_id": "...",
  "from":    { "name": "...", "email": "..." },
  "to":      [ { "name": "...", "email": "..." } ],
  "cc":      [ ... ],
  "subject": "...",
  "date":    "Mon, 3 May 2026 10:00:00 -0700",
  "body_text": "decoded plain-text body",
  "snippet":   "first ~200 chars from Gmail",
  "labels":  [ "INBOX", "IMPORTANT", ... ],
  "attachments": [
    { "id": "...", "filename": "invoice.pdf",
      "mime_type": "application/pdf", "size": 12345 }
  ]
}
```

Useful `jq` paths:

```jq
.subject
.from.email
.body_text
.labels[]
.attachments[] | .filename
```

To act on messages (read by id, triage, raw API calls), use the `gws`
CLI if installed (`gws gmail --help`).

## Supported Unix Commands for VFS

Unix commands work on each path as on a local filesystem, as far as the path supports them:

| Path | Supported |
| --- | --- |
| `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `grep -r` and `rg` ask `gmail` which files may match. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Read only: no command changes files. `gmail` answers only for `*/*/*.gmail.json`; `grep -r` and `rg` read every other file. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |

Run `man <cmd>` or `<cmd> --help` for one command's usage.

Integration

What Gmail answers through its own API, so fewer files are read. Integration explains each command.

Command	On Gmail
`grep -r`, `rg`	The message text the listing keeps, for ASCII text. It misses nothing.

The Python Gmail docs list when each search answers and what it can miss.

Mount mode

read. For the mounted layout (labels, dates, attachments) see the Python Gmail docs.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Browser

Config

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

Mount mode

​Node

​Browser

​Config

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

​Mount mode

Node

Browser

Config

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

Mount mode