Google Docs

GDocsVFS exposes Google Docs as .gdoc.json files. Reads return the document’s structured content. Setup steps for OAuth credentials live at Google Workspace Credentials.

Node

pnpm add @struktoai/mirage-node

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

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

const ws = new Workspace({ '/docs': docs }, { mode: MountMode.WRITE })
await ws.shell('cat /docs/owned/MyDoc.gdoc.json')

Browser

pnpm add @struktoai/mirage-browser

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

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

const ws = new Workspace({ '/docs': docs }, { mode: MountMode.WRITE })

A PKCE example lives at examples/browser/vfs/gdocs/gdocs_pkce.ts.

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.

Mount mode

read. A MountMode.WRITE mount also allows mv (retitle) and rm (delete). Append text with the gws CLI. For the JSON shape see the Python Google Docs docs.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

VFS Layout

`/<path>`

/<path>
  owned/     # docs you created
    <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json
  shared/    # docs others shared with you
    <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json

<YYYY-MM-DD> is the file’s modifiedTime, so a date glob such as 2026-05-* narrows by it.
<title> is sanitized: spaces and any character outside [A-Za-z0-9_.-] become _, at most 100 characters.
<doc-id> is the Google Docs document id.
shared/ holds docs shared with you by others; ones you own and shared with others are still in owned/.

A .gdoc.json holds the Google Docs API documents.get response, read with includeTabsContent=true so every tab is present:

{
  "documentId": "...",
  "title": "...",
  "tabs": [                            // one entry per top-level tab
    {
      "tabProperties": {
        "tabId": "t.0",                // names a tab for gws docs write
        "title": "Tab 1",
        "index": 0
      },
      "documentTab": {
        "body": {
          "content": [
            {                          // one element per block
              "paragraph": {
                "elements": [
                  { "textRun": { "content": "the actual text\n",
                                 "textStyle": {...} } }
                ],
                "paragraphStyle": {...}
              }
            },
            { "table": {...} },
            { "sectionBreak": {...} }
          ]
        },
        "documentStyle": {...},
        "namedStyles": {...}
      },
      "childTabs": [ { ...same shape, nested to any depth... } ]
                                       // a nested tab also carries
                                       // parentTabId and nestingLevel;
                                       // a root tab carries neither
    }
  ],
  "revisionId": "..."
}

There is no top-level .body. A tab-aware response leaves the singleton fields (.body, .documentStyle, .namedStyles) empty and hangs every tab’s content off .tabs[].documentTab instead. Tabs also nest, so text can sit at any depth under .childTabs; the recursive recipes below read a one-tab and a fifty-tab document alike.Useful jq paths:

.title
[.. | .tabProperties? // empty | .title]             # every tab name
[.. | .textRun? // empty | .content] | add           # all text, any depth
[.. | .tabProperties? // empty] | length             # tab count
[.tabs[0].documentTab.body.content[]
      | .paragraph?.elements[]?.textRun.content] | add   # first tab only
.revisionId

The first block of a body is always a sectionBreak, which carries no .paragraph, so a path through .paragraph needs the ? or it fails with Cannot iterate over null.Delete, on a write path:

rm /<path>/owned/<file>.gdoc.json   # deletes it from Drive for good
rm -f <path>                       # ignores a missing file

Only .gdoc.json files can be removed; owned/ and shared/ cannot.Rename to a new title, on a write path:

mv /<path>/owned/<date>_<old>__<id>.gdoc.json \
   /<path>/owned/<date>_<new>__<id>.gdoc.json

Keep the folder, the date and the id, and spell the title the way the listing does (spaces become _); any other name is refused.

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), and `mv`, `rm` and `unlink`. `grep -r` and `rg` with `-w` ask `gdocs` which files may match.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	Not supported: `>`, `>>`, `tee`, `tee -a`, `touch` of a new file, `cp`, `cp -r`, `mkdir`, `rm -r`, `rmdir`, `truncate`, `sed -i`. 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>` | `gdocs`, write |

## VFS Layout

### `/<path>`

```text
/<path>
  owned/     # docs you created
    <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json
  shared/    # docs others shared with you
    <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json
```

- `<YYYY-MM-DD>` is the file's `modifiedTime`, so a date glob such as
  `2026-05-*` narrows by it.
- `<title>` is sanitized: spaces and any character outside
  `[A-Za-z0-9_.-]` become `_`, at most 100 characters.
- `<doc-id>` is the Google Docs document id.
- `shared/` holds docs shared with you by others; ones you own
  and shared with others are still in `owned/`.

A `.gdoc.json` holds the Google Docs API `documents.get` response, read
with `includeTabsContent=true` so every tab is present:

```jsonc
{
  "documentId": "...",
  "title": "...",
  "tabs": [                            // one entry per top-level tab
    {
      "tabProperties": {
        "tabId": "t.0",                // names a tab for gws docs write
        "title": "Tab 1",
        "index": 0
      },
      "documentTab": {
        "body": {
          "content": [
            {                          // one element per block
              "paragraph": {
                "elements": [
                  { "textRun": { "content": "the actual text\n",
                                 "textStyle": {...} } }
                ],
                "paragraphStyle": {...}
              }
            },
            { "table": {...} },
            { "sectionBreak": {...} }
          ]
        },
        "documentStyle": {...},
        "namedStyles": {...}
      },
      "childTabs": [ { ...same shape, nested to any depth... } ]
                                       // a nested tab also carries
                                       // parentTabId and nestingLevel;
                                       // a root tab carries neither
    }
  ],
  "revisionId": "..."
}
```

There is no top-level .body. A tab-aware response leaves the singleton
fields (`.body`, `.documentStyle`, `.namedStyles`) empty and hangs every
tab's content off `.tabs[].documentTab` instead. Tabs also nest, so text
can sit at any depth under `.childTabs`; the recursive recipes below read
a one-tab and a fifty-tab document alike.

Useful `jq` paths:

```jq
.title
[.. | .tabProperties? // empty | .title]             # every tab name
[.. | .textRun? // empty | .content] | add           # all text, any depth
[.. | .tabProperties? // empty] | length             # tab count
[.tabs[0].documentTab.body.content[]
      | .paragraph?.elements[]?.textRun.content] | add   # first tab only
.revisionId
```

The first block of a body is always a `sectionBreak`, which carries no
`.paragraph`, so a path through `.paragraph` needs the `?` or it fails
with `Cannot iterate over null`.

Delete, on a `write` path:

```sh
rm /<path>/owned/<file>.gdoc.json   # deletes it from Drive for good
rm -f <path>                       # ignores a missing file
```

Only `.gdoc.json` files can be removed; `owned/` and `shared/` cannot.

Rename to a new title, on a `write` path:

```sh
mv /<path>/owned/<date>_<old>__<id>.gdoc.json \
   /<path>/owned/<date>_<new>__<id>.gdoc.json
```

Keep the folder, the date and the id, and spell the title the way the
listing does (spaces become `_`); any other name is refused.

## 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), and `mv`, `rm` and `unlink`. `grep -r` and `rg` with `-w` ask `gdocs` which files may match. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | Not supported: `>`, `>>`, `tee`, `tee -a`, `touch` of a new file, `cp`, `cp -r`, `mkdir`, `rm -r`, `rmdir`, `truncate`, `sed -i`. 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.

Integration

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

Command	On Google Docs
`grep -r`, `rg`	Drive full-text search, for whole words. It can miss words only in non-text values (fonts, links and ids) or split by styling.

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

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​Node

​Browser

​Config

​Mount mode

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

Node

Browser

Config

Mount mode

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration