Google Drive

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

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.gdrive import GoogleDriveConfig, GoogleDriveVFS

config = GoogleDriveConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
)
vfs = GoogleDriveVFS(config=config)
ws = Workspace({"/gdrive": vfs}, mode=MountMode.WRITE)

To mount a subfolder instead of the whole Drive, set folder_id. The mount root becomes that folder. The folder may live in My Drive, be shared with you, sit inside a Shared Drive, or be a Shared Drive id itself; the drive scope is resolved automatically. Scoped mounts do not surface other shared drives:

config = GoogleDriveConfig(
    client_id=os.environ["GOOGLE_CLIENT_ID"],
    client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
    refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
    folder_id="1AbCdEfFolderId",
)

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.
`folder_id`	Drive folder ID the `gdrive` mount uses as its root instead of My Drive; it may be a folder in a Shared Drive. Other Google mounts ignore it.

Fields marked secret are redacted in snapshots.

VFS.md

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

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`gdrive`, write

`/<path>` layout

/<path>
  Mirrors Google Drive folder hierarchy. May contain:
    <name>.gdoc.json    Google Docs    (cat returns gdoc.json - see /gdocs layout)
    <name>.gsheet.json  Google Sheets  (cat returns gsheet.json - see /gsheets layout)
    <name>.gslide.json  Google Slides  (cat returns gslide.json - see /gslides layout)
    <other-files>       PDFs, images, etc. - cat returns raw bytes

  No owned/ vs shared/ split here: gdrive shows the user's full Drive view,
  including files shared with the user that have been added to My Drive.
  Shared drives visible to the user are included as top-level directories.

  IMPORTANT: This is a remote mount. Prefer targeted reads over full scans.
  Date-prefixed globs (2026-05-*) push to a Drive modifiedTime range query.

  To act on Drive items by id (create, update, export, permissions),
  use the gws CLI if installed: gws drive --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>`	Almost all Unix commands. `grep -r` and `rg` with `-w` ask `gdrive` which files may match.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Without `-w`, `grep -r` and `rg` read every 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>` | `gdrive`, write |

## `/<path>` layout

```text
/<path>
  Mirrors Google Drive folder hierarchy. May contain:
    <name>.gdoc.json    Google Docs    (cat returns gdoc.json - see /gdocs layout)
    <name>.gsheet.json  Google Sheets  (cat returns gsheet.json - see /gsheets layout)
    <name>.gslide.json  Google Slides  (cat returns gslide.json - see /gslides layout)
    <other-files>       PDFs, images, etc. - cat returns raw bytes

  No owned/ vs shared/ split here: gdrive shows the user's full Drive view,
  including files shared with the user that have been added to My Drive.
  Shared drives visible to the user are included as top-level directories.

  IMPORTANT: This is a remote mount. Prefer targeted reads over full scans.
  Date-prefixed globs (2026-05-*) push to a Drive modifiedTime range query.

  To act on Drive items by id (create, update, export, permissions),
  use the gws CLI if installed: gws drive --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>` | Almost all Unix commands. `grep -r` and `rg` with `-w` ask `gdrive` which files may match. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Without `-w`, `grep -r` and `rg` read every 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.

/gdrive/
  <folder>/
    <file>
    <subfolder>/
      ...
    <name>.gdoc.json
    <name>.gsheet.json
    <name>.gslide.json
  <shared-drive>/
    <file>
    <folder>/

Example:

/gdrive/
  Projects/
    spec.pdf
    roadmap.gsheet.json
    Budget/
      Q1.gsheet.json
      Q2.gsheet.json
  Notes/
    meeting.gdoc.json
  Presentations/
    quarterly_review.gslide.json
  Team Drive/
    shared-spec.pdf
  data.csv
  report.pdf

The mount mirrors the actual Google Drive folder hierarchy. The root contains the Drive API root folder plus each Shared Drive visible to the user. Shared Drives appear as top-level directories. Duplicate names receive a [Shared Drive] suffix and, when needed, a numeric suffix. Subfolders appear as directories, and regular files keep their original names.

Synthetic Extensions

Google Workspace files cannot be downloaded as raw bytes, so they are exposed with synthetic extensions and read via their respective APIs:

Extension	Type	Read via
`.gdoc.json`	Google Docs	Docs API
`.gsheet.json`	Google Sheets	Sheets API
`.gslide.json`	Google Slides	Slides API

Regular files (PDFs, images, CSVs, etc.) are downloaded directly from Drive. Large regular files use streaming.

Write Support

Under MountMode.WRITE the standard write commands work on regular files and folders: tee, cp, mv, rm, mkdir, rmdir, touch, truncate, and in-place editors such as sed -i. Semantics follow the other object-store mounts (GNU check-then-act: EEXIST on mkdir over an existing name, mv onto a non-empty directory fails with ENOTEMPTY, cp -r merges). Google-native files (.gdoc.json, .gsheet.json, .gslide.json) are read-only as bytes; writing to them fails with EACCES. Mutate them through the gws commands below instead. Drive access is per-item (shared-drive roles, folder-level grants), so a write mount can still hold items you may not edit. A mutation the API denies fails with EACCES (Permission denied) on that operand, like a real filesystem; the rest of the mount keeps working. A write records the md5Checksum (else the headRevisionId) its upload reply names, so a fresh read right after a tee or sed -i downloads nothing. Use MountMode.EXEC if python3 or js should run scripts from the mount.

Writing inside a Shared Drive

A Shared Drive is not a read-only corner of the mount. Every Drive call mirage makes carries supportsAllDrives, so create, write, rename, copy and delete work the same inside a Shared Drive as in My Drive, and the commands above behave identically there. What you may actually do is decided by Drive, not by mirage: a Shared Drive has its own role model (viewer, commenter, contributor, content manager, manager), and some organizations restrict deletion or moving content out of the drive. mirage does not attempt to predict those rules. It issues the operation and reports the answer, so a role that forbids the change fails with EACCES on that operand, exactly like an unwritable item in My Drive. The practical consequence is that a write mount spanning Shared Drives is partly writable, and the boundary follows your roles rather than the mount. If you want a mount that cannot write at all, use MountMode.READ; if you want to scope one to a single drive, set folder_id to the Shared Drive id.

Snapshots

The VFS supports workspace snapshots. Recorded reads capture the file’s Drive revision (headRevisionId), and a loaded snapshot pins reads to that revision via the Drive Revisions API, so replay serves the exact bytes the agent saw. A path the agent wrote carries its write’s token and no revision: loading checks the live file against that token, and replay reads the live file rather than a pinned revision. Google Docs, Sheets and Slides files carry no revision: loading checks them against the live file instead.

Cache

The Google Drive VFS uses IndexCacheStore (same as Slack, Gmail, and other mounts). Index entries store folder IDs, file IDs, and file 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.gdrive import GoogleDriveConfig, GoogleDriveVFS

load_dotenv(".env.development")

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


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

    # List root
    r = await ws.shell("ls /gdrive/ | head -n 10")
    print(await r.stdout_str())

    # Browse a subfolder
    r = await ws.shell("ls /gdrive/Projects/")
    print(await r.stdout_str())

    # Read a regular file
    r = await ws.shell("cat /gdrive/Projects/spec.pdf | head -c 200")
    print(await r.stdout_str())

    # Read a Google Doc title
    r = await ws.shell('jq ".title" /gdrive/Notes/meeting.gdoc.json')
    print(await r.stdout_str())

    # Read a Google Sheet title
    r = await ws.shell(
        'jq ".properties.title" /gdrive/Projects/roadmap.gsheet.json')
    print(await r.stdout_str())

    # Read a Google Slides deck length
    r = await ws.shell(
        'jq ".slides | length"'
        " /gdrive/Presentations/quarterly_review.gslide.json")
    print(await r.stdout_str())

    # Search across all files
    r = await ws.shell('rg "quarterly" /gdrive/Projects/')
    print(await r.stdout_str())

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

    # Create a new Google Doc
    r = await ws.shell(
        "gws docs documents create"
        ' --json \'{"title": "New Doc from MIRAGE"}\'')
    print(await r.stdout_str())


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

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

Shell Commands

Standard commands available on the mounted Google Drive tree:

Command	Notes
`ls`	List folders and files
`cat`	Read file content (regular or Workspace)
`head` / `tail`	First/last N lines or bytes
`grep` / `rg`	Pattern search (file or directory level)
`jq`	Query JSON fields on Workspace files
`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
`sort`	Sort lines
`uniq`	Deduplicate adjacent lines
`cut`	Extract fields/columns
`awk`	Pattern-directed scanning
`sed`	Stream editor
`tr`	Translate/delete characters
`diff`	Compare two files
`rev`	Reverse lines
`tac`	Reverse file line order
`paste`	Merge lines of files
`join`	Join lines on a common field
`column`	Columnate output
`comm`	Compare sorted files line by line
`fold`	Wrap lines to a given width
`fmt`	Reformat paragraph text
`expand`	Convert tabs to spaces
`unexpand`	Convert spaces to tabs
`du`	Estimate file space usage
`shuf`	Randomly permute lines
`look`	Display lines beginning with a prefix
`strings`	Extract printable strings from binary
`base64`	Base64 encode/decode
`md5`	MD5 checksum
`sha256sum`	SHA-256 checksum
`xxd`	Hex dump
`zcat`	Read compressed files
`zgrep`	Search compressed files
`readlink`	Print resolved symbolic links
`cmp`	Compare two files byte by byte
`tsort`	Topological sort
`file`	Detect file type

Integration

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

Command	On Google Drive
`grep -r`, `rg`	Drive full-text search, for whole words (`-w`, `-x`). It can miss Docs, Sheets and Slides JSON, office files, PDFs, archives, the end of large files, words Drive splits differently (`foo.bar`) and recent writes.
`md5sum`, `sha1sum`, `sha256sum`	The digest Drive keeps; a Docs, Sheets or Slides file is read
`find`, `du`, `ls -R`, `tree`	One recursive listing

grep -rw and rg -w read only the files Drive full-text search names; every file is read when the search fails or finds nothing. walk_limit: -1 in the mount’s "@all" command limit reads every file instead, since Drive searches the text it extracted, not the bytes grep reads, and indexes a write some time after it lands, so a file that holds the word can be left out: a Docs, Sheets or Slides file (its JSON keys and ids), an office file, PDF or archive, the end of a large file, or a word Drive splits differently (foo.bar).

Acting on Drive

Acting on Drive files by id (create, update, copy, delete, share, export, plus the Docs/Sheets/Slides helpers) goes through the gws CLI when installed.

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

Synthetic Extensions

Write Support

Writing inside a Shared Drive

Snapshots

Cache

Example

Shell Commands

Integration

Acting on Drive

​Config

​VFS.md

​Virtual Filesystem

​/<path> layout

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Synthetic Extensions

​Write Support

​Writing inside a Shared Drive

​Snapshots

​Cache

​Example

​Shell Commands

​Integration

​Acting on Drive

Config

VFS.md

Virtual Filesystem

`/<path>` layout

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Synthetic Extensions

Write Support

Writing inside a Shared Drive

Snapshots

Cache

Example

Shell Commands

Integration

Acting on Drive