Gmail

The Gmail VFS exposes a Gmail account as a virtual filesystem mounted at some prefix such as /gmail/. For Google OAuth setup, see Google Workspace Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.gmail import GmailConfig, GmailVFS

config = GmailConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
vfs = GmailVFS(config=config)
ws = Workspace({"/gmail": vfs}, mode=MountMode.READ)

Field	Description
`timeout` default `30`	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.
`access_token` secret	OAuth access token, or a callable that returns one. Takes precedence over `client_id` and `refresh_token`.
`client_id`	Google OAuth client ID. Required with `refresh_token` when `access_token` is unset; mirage then mints and renews access tokens itself.
`client_secret` secret	Google OAuth client secret, sent with the refresh-token grant. Omit it for a PKCE client.
`refresh_token` secret	User’s OAuth refresh token. Required with `client_id` when `access_token` is unset.
`api_base`	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

`/<path>` layout

/<path>
  <label>/
    <yyyy-mm-dd>/
      <subject>__<message-id>.gmail.json    # email JSON file (the email itself)
      <subject>__<message-id>/              # attachments dir, only if any
        <attachment-filename>

  Email body is in the .gmail.json file. The sibling dir holds attachments
  only. Read with `cat`/`head`/`jq` on `<path>.gmail.json` (keep the suffix).

  Path: <label>/<yyyy-mm-dd>/<subject>__<message-id>.gmail.json
    <label>       Gmail label (INBOX, SENT, DRAFT, IMPORTANT, STARRED,
                  TRASH, SPAM, or any user label)
    <yyyy-mm-dd>  date the message was received, used for date narrowing
                  (ls /<path>/INBOX/2026-05-03/ pushes after:/before: into the
                  Gmail query - much cheaper than scanning the whole label)
    <subject>     sanitized subject (don't construct it; ls the date dir)
    <message-id>  Gmail message ID

  email JSON structure (mirage-processed, 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 }
      ]
    }

  Attachments: each message with attachments has a sibling directory at
  <subject>__<message-id>/ (same name as the .gmail.json file but without
  the extension). Cat a file inside to download bytes. grep -r over a
  date dir skips these binary files automatically.

  After a grep/rg hit, the result line points to .../<subject>__<id>.gmail.json
  — the sibling attachments dir is NOT in grep output. Once you have the
  message id (or the .gmail.json path), ls the same path with .gmail.json
  stripped to list attachments directly:
    ls /<path>/INBOX/2026-05-03/<subject>__<message-id>/
  ENOENT means the message has no attachments.

  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 |

## `/<path>` layout

```text
/<path>
  <label>/
    <yyyy-mm-dd>/
      <subject>__<message-id>.gmail.json    # email JSON file (the email itself)
      <subject>__<message-id>/              # attachments dir, only if any
        <attachment-filename>

  Email body is in the .gmail.json file. The sibling dir holds attachments
  only. Read with `cat`/`head`/`jq` on `<path>.gmail.json` (keep the suffix).

  Path: <label>/<yyyy-mm-dd>/<subject>__<message-id>.gmail.json
    <label>       Gmail label (INBOX, SENT, DRAFT, IMPORTANT, STARRED,
                  TRASH, SPAM, or any user label)
    <yyyy-mm-dd>  date the message was received, used for date narrowing
                  (ls /<path>/INBOX/2026-05-03/ pushes after:/before: into the
                  Gmail query - much cheaper than scanning the whole label)
    <subject>     sanitized subject (don't construct it; ls the date dir)
    <message-id>  Gmail message ID

  email JSON structure (mirage-processed, 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 }
      ]
    }

  Attachments: each message with attachments has a sibling directory at
  <subject>__<message-id>/ (same name as the .gmail.json file but without
  the extension). Cat a file inside to download bytes. grep -r over a
  date dir skips these binary files automatically.

  After a grep/rg hit, the result line points to .../<subject>__<id>.gmail.json
  — the sibling attachments dir is NOT in grep output. Once you have the
  message id (or the .gmail.json path), ls the same path with .gmail.json
  stripped to list attachments directly:
    ls /<path>/INBOX/2026-05-03/<subject>__<message-id>/
  ENOENT means the message has no attachments.

  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.

/gmail/
  <label>/
    <yyyy-mm-dd>/
      <sanitized-subject>__<message-id>.gmail.json
      <sanitized-subject>__<message-id>/   # only if message has attachments
        <attachment-filename>
        ...

Example:

/gmail/
  INBOX/
    2026-04-12/
      Meeting_Notes__msg123.gmail.json
      Meeting_Notes__msg123/
        report.pdf
        screenshot.png
      Simple_Email__msg456.gmail.json
    2026-04-11/
      Hello__msg789.gmail.json
  SENT/
    2026-04-12/
      Reply__msg012.gmail.json
  STARRED/
  My_Custom_Label/

Label directories appear at the root. System labels use the Gmail label ID (e.g., INBOX, SENT, STARRED). User-created labels use their label name as is.

Date Directories

Inside each label, messages are grouped into date subdirectories formatted as YYYY-MM-DD. The date is derived from the message’s internalDate (epoch milliseconds) converted to a calendar date.

Message Files

Each message is stored as a .gmail.json file. The filename shape is:

<sanitized-subject>__<message-id>.gmail.json

Subjects are sanitized for filesystem safety and truncated when necessary. The message ID is embedded after __ and before .gmail.json.

Attachments

Messages that have attachments get a companion subdirectory with the same base name (without .gmail.json). Decoded attachment files are placed inside:

Meeting_Notes__msg123.gmail.json    # message JSON
Meeting_Notes__msg123/              # attachment directory
  report.pdf
  screenshot.png

Cache

The Gmail VFS uses IndexCacheStore (same as Slack, Discord, and other mounts). Index entries store label IDs, message IDs, and message metadata. File bytes go through the workspace file cache.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.commands.cli.builtin.gws import GWS
from mirage.vfs.gmail import GmailConfig, GmailVFS

load_dotenv(".env.development")

config = GmailConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
vfs = GmailVFS(config=config)


async def main():
    ws = Workspace({"/gmail": vfs}, mode=MountMode.READ)
    ws.register_cli("gws", GWS, config)

    # List labels
    r = await ws.shell("ls /gmail/")
    print(await r.stdout_str())

    # List date directories in INBOX
    r = await ws.shell("ls /gmail/INBOX/")
    print(await r.stdout_str())

    # List messages for a specific date
    r = await ws.shell("ls /gmail/INBOX/2026-04-12/")
    print(await r.stdout_str())

    # Read a message
    r = await ws.shell(
        "cat /gmail/INBOX/2026-04-12/Meeting_Notes__msg123.gmail.json")
    print(await r.stdout_str())

    # Extract subject with jq
    r = await ws.shell(
        'jq ".subject"'
        " /gmail/INBOX/2026-04-12/Meeting_Notes__msg123.gmail.json")
    print(await r.stdout_str())

    # List attachments
    r = await ws.shell("ls /gmail/INBOX/2026-04-12/Meeting_Notes__msg123/")
    print(await r.stdout_str())

    # Search across all messages
    r = await ws.shell('rg "quarterly" /gmail/INBOX/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.shell("tree -L 2 /gmail/INBOX/")
    print(await r.stdout_str())

    # Triage unread messages
    r = await ws.shell('gws gmail triage --query "is:unread" --max 5')
    print(await r.stdout_str())

    # Send an email
    r = await ws.shell(
        'gws gmail send --to "user@example.com"'
        ' --subject "Hello from MIRAGE"'
        ' --body "This email was sent via the MIRAGE Gmail VFS."')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

See examples/python/vfs/gmail/gmail.py for the full working example.

Finding IDs

VFS-specific commands require message IDs. These can be extracted from the filesystem:

# Message ID -- embedded in filename after "__"
ls /gmail/INBOX/2026-04-12/
# -> Meeting_Notes__msg123.gmail.json   <- message_id = msg123

# Extract message ID from filename
basename /gmail/INBOX/2026-04-12/Meeting_Notes__msg123.gmail.json .gmail.json
# -> Meeting_Notes__msg123
# The part after "__" is the message ID: msg123

# Read a message then reply
gws gmail read --id msg123
gws gmail reply --message-id msg123 --body "Thanks for the notes"

Working with Large Labels

Labels with many messages are split into date directories. A bare ls of a label lists the days of its 50 most recent messages; a glob over the date names (ls /gmail/INBOX/2026-03-*) or a date directory by name reaches older days. Tips for efficient access:

# List available dates
ls /gmail/INBOX/

# Check message count for a specific date
ls /gmail/INBOX/2026-04-12/ | wc -l

# Read only the most recent date
ls /gmail/INBOX/ | tail -n 1

# Search across all dates in a label
rg "keyword" /gmail/INBOX/

# Extract specific fields to reduce output
jq -r '.subject' /gmail/INBOX/2026-04-12/*.gmail.json | head -n 20

# Find messages with attachments
find /gmail/INBOX/2026-04-12/ -type d

# Tree view of a label
tree -L 2 /gmail/INBOX/

Shell Commands

Standard commands available on the mounted Gmail tree:

Command	Notes
`ls`	List labels, dates, messages, attachments
`cat`	Read message JSON or attachment content
`head` / `tail`	First/last N lines
`grep` / `rg`	Pattern search (file or directory level)
`jq`	Query message JSON fields
`wc`	Line/word/byte counts
`stat`	File metadata (name, size, type)
`find`	Recursive search with `-name`, `-maxdepth`
`tree`	Directory tree view
`basename`	Extract filename from path
`dirname`	Extract directory from path
`realpath`	Resolve path to absolute form
`nl`	Number lines of output

Acting on Gmail (send, reply, forward, triage, raw API calls) goes through the gws CLI when installed.

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 listing keeps each message’s text, and grep -r and rg read only the messages whose text holds the pattern’s text in any case, printing what reading every message would. Listing a label already fetches its messages in full, so this asks Gmail nothing more and saves the second fetch of each message it rules out. Gmail’s own search is not used: it reads the HTML part of a message and can miss a word of the plain-text body a .gmail.json holds, such as one inside a link. 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 a message’s labels change after the listing kept its text. With walk_limit: -1 in the mount’s "@all" command limit, the listing keeps no message text, and every message is read.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Date Directories

Message Files

Attachments

Cache

Example

Finding IDs

Working with Large Labels

Shell Commands

Integration

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Date Directories

​Message Files

​Attachments

​Cache

​Example

​Finding IDs

​Working with Large Labels

​Shell Commands

​Integration

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Date Directories

Message Files

Attachments

Cache

Example

Finding IDs

Working with Large Labels

Shell Commands

Integration