Mirage · Unified Virtual Filesystem for AI Agents

The Google Drive resource 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.resource.gdrive import GoogleDriveConfig, GoogleDriveResource

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

Filesystem Layout

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

Example:

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

The mount mirrors the actual Google Drive folder hierarchy. The root of the mount corresponds to the Drive API root folder. 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.

Cache

The Google Drive resource uses IndexCacheStore (same as Slack, Gmail, and other resources). Index entries store folder IDs, file IDs, and file metadata. There is no separate content cache — file content caching is handled by the workspace IOResult mechanism.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.gdrive import GoogleDriveConfig, GoogleDriveResource

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"],
)
resource = GoogleDriveResource(config=config)


async def main():
    ws = Workspace({"/gdrive": resource}, mode=MountMode.READ)

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

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

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

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

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

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

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

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

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


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

See examples/google/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

Data Format Support

Google Drive may contain data files in binary columnar formats. These are auto-converted to CSV on read. Specialized variants of common commands handle them natively:

Format	Extension	Specialized commands
Parquet	`.parquet`	`cat-parquet`, `head-parquet`, `tail-parquet`, `wc-parquet`, `stat-parquet`, `grep-parquet`, `cut-parquet`, `ls-parquet`, `file-parquet`
Feather	`.feather`	`cat-feather`, `head-feather`, `tail-feather`, `wc-feather`, `stat-feather`, `grep-feather`, `cut-feather`, `ls-feather`, `file-feather`
HDF5	`.hdf5`	`cat-hdf5`, `head-hdf5`, `tail-hdf5`, `wc-hdf5`, `stat-hdf5`, `grep-hdf5`, `cut-hdf5`, `ls-hdf5`, `file-hdf5`
ORC	`.orc`	`cat-orc`, `head-orc`, `tail-orc`, `wc-orc`, `stat-orc`, `grep-orc`, `cut-orc`, `ls-orc`, `file-orc`

Example:

cat-parquet /gdrive/data/sales.parquet
head-parquet -n 5 /gdrive/data/sales.parquet
grep-parquet "revenue" /gdrive/data/sales.parquet
wc-parquet /gdrive/data/sales.parquet

Resource-Specific Commands

Google Drive registers Google Workspace write commands so that Google-native files can be created and updated from the Drive mount.

`gws-docs-documents-create`

Create a new Google Doc.

gws-docs-documents-create --json '{"title": "My Doc"}'

Option	Required	Description
`--json`	yes	JSON body with `title` field

Returns the created document JSON.

`gws-docs-documents-batchUpdate`

Apply batch updates to a Google Doc.

gws-docs-documents-batchUpdate \
  --params '{"documentId": "DOC_ID"}' \
  --json '{"requests": [...]}'

Option	Required	Description
`--params`	yes	JSON with `documentId`
`--json`	yes	JSON body with `requests` array

Returns the batch update response JSON.

`gws-docs-write`

Append text to a Google Doc.

gws-docs-write --document DOC_ID --text "Hello from MIRAGE"

Option	Required	Description
`--document`	yes	Google Doc ID
`--text`	yes	Text to append

Returns the update response JSON.

`gws-sheets-read`

Read values from a spreadsheet range.

gws-sheets-read --spreadsheet SHEET_ID --range "Sheet1!A1:C10"

Option	Required	Description
`--spreadsheet`	yes	Spreadsheet ID
`--range`	yes	A1 notation range

Returns the range values.

`gws-sheets-write`

Write values to a spreadsheet range.

gws-sheets-write \
  --params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1:C3", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["a", "b", "c"]]}'

Option	Required	Description
`--params`	yes	JSON with `spreadsheetId`, `range`, optional `valueInputOption`
`--json`	yes	JSON body with `values` array

Returns the update response JSON.

`gws-sheets-append`

Append rows to a spreadsheet.

gws-sheets-append --spreadsheet SHEET_ID --range "Sheet1!A1" --values "a,b,c"

Option	Required	Description
`--spreadsheet`	yes	Spreadsheet ID
`--range`	no	A1 notation range (defaults to `A1`)
`--values`	no	Comma-separated values for a single row
`--json-values`	no	JSON array of rows (alternative to `--values`)

One of --values or --json-values is required. Returns the append response JSON.

`gws-sheets-spreadsheets-create`

Create a new spreadsheet.

gws-sheets-spreadsheets-create --json '{"properties": {"title": "My Sheet"}}'

Option	Required	Description
`--json`	yes	JSON body with `properties.title`

Returns the created spreadsheet JSON.

`gws-sheets-spreadsheets-batchUpdate`

Apply batch updates to a spreadsheet.

gws-sheets-spreadsheets-batchUpdate \
  --params '{"spreadsheetId": "SHEET_ID"}' \
  --json '{"requests": [...]}'

Option	Required	Description
`--params`	yes	JSON with `spreadsheetId`
`--json`	yes	JSON body with `requests` array

Returns the batch update response JSON.

`gws-slides-presentations-create`

Create a new Google Slides presentation.

gws-slides-presentations-create --json '{"title": "My Deck"}'

Option	Required	Description
`--json`	yes	JSON body with `title` field

Returns the created presentation JSON.

`gws-slides-presentations-batchUpdate`

Apply batch updates to a presentation.

gws-slides-presentations-batchUpdate \
  --params '{"presentationId": "PRES_ID"}' \
  --json '{"requests": [...]}'

Option	Required	Description
`--params`	yes	JSON with `presentationId`
`--json`	yes	JSON body with `requests` array

Returns the batch update response JSON.

Getting Started

Agents

Resources

Google Drive

Config

Filesystem Layout

Synthetic Extensions

Cache

Example

Shell Commands

Data Format Support

Resource-Specific Commands

`gws-docs-documents-create`

`gws-docs-documents-batchUpdate`

`gws-docs-write`

`gws-sheets-read`

`gws-sheets-write`

`gws-sheets-append`

`gws-sheets-spreadsheets-create`

`gws-sheets-spreadsheets-batchUpdate`

`gws-slides-presentations-create`

`gws-slides-presentations-batchUpdate`

Getting Started

Agents

Resources

Documentation Index

​Config

​Filesystem Layout

​Synthetic Extensions

​Cache

​Example

​Shell Commands

​Data Format Support

​Resource-Specific Commands

​gws-docs-documents-create

​gws-docs-documents-batchUpdate

​gws-docs-write

​gws-sheets-read

​gws-sheets-write

​gws-sheets-append

​gws-sheets-spreadsheets-create

​gws-sheets-spreadsheets-batchUpdate

​gws-slides-presentations-create

​gws-slides-presentations-batchUpdate

Config

Filesystem Layout

Synthetic Extensions

Cache

Example

Shell Commands

Data Format Support

Resource-Specific Commands

`gws-docs-documents-create`

`gws-docs-documents-batchUpdate`

`gws-docs-write`

`gws-sheets-read`

`gws-sheets-write`

`gws-sheets-append`

`gws-sheets-spreadsheets-create`

`gws-sheets-spreadsheets-batchUpdate`

`gws-slides-presentations-create`

`gws-slides-presentations-batchUpdate`