Google Sheets

GSheetsVFS exposes Google Sheets as .gsheet.json files. Reads return cell values. Setup steps for OAuth credentials live at Google Workspace Credentials.

Node

pnpm add @struktoai/mirage-node

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

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

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

Browser

pnpm add @struktoai/mirage-browser

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

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

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). Write cells with the gws CLI. For the layout and sheet/tab structure see the Python Sheets docs.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

VFS Layout

`/<path>`

/<path>
  owned/     # sheets you created
    <YYYY-MM-DD>_<title>__<spreadsheet-id>.gsheet.json
  shared/    # sheets others shared with you
    <YYYY-MM-DD>_<title>__<spreadsheet-id>.gsheet.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.
<spreadsheet-id> is the Google Sheets spreadsheet id.
shared/ holds sheets shared with you by others; ones you own and shared with others are still in owned/.

A .gsheet.json matches the Google Sheets API spreadsheets.get response:

{
  "spreadsheetId": "...",
  "spreadsheetUrl": "...",
  "properties": { "title": "...", "locale": "...", "timeZone": "..." },
  "sheets": [
    {                                      // one element per tab
      "properties": {
        "sheetId": 0, "title": "...", "index": 0,
        "gridProperties": { "rowCount": 1000, "columnCount": 26 }
      },
      "data": [
        {
          "rowData": [
            { "values": [
                { "formattedValue": "...",
                  "userEnteredValue": {...},
                  "effectiveValue": {...} }
            ]}    // an empty cell is {}, a trailing one absent
          ]
        }
      ]
    }
  ],
  "namedRanges": [...]
}

Useful jq paths:

.properties.title
.sheets[].properties.title                              # tab names
.sheets[0].data[0].rowData[].values[].formattedValue    # cell strings
.namedRanges[]

Delete, on a write path:

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

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

mv /<path>/owned/<date>_<old>__<id>.gsheet.json \
   /<path>/owned/<date>_<new>__<id>.gsheet.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 `gsheets` 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>` | `gsheets`, write |

## VFS Layout

### `/<path>`

```text
/<path>
  owned/     # sheets you created
    <YYYY-MM-DD>_<title>__<spreadsheet-id>.gsheet.json
  shared/    # sheets others shared with you
    <YYYY-MM-DD>_<title>__<spreadsheet-id>.gsheet.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.
- `<spreadsheet-id>` is the Google Sheets spreadsheet id.
- `shared/` holds sheets shared with you by others; ones you own
  and shared with others are still in `owned/`.

A `.gsheet.json` matches the Google Sheets API `spreadsheets.get`
response:

```jsonc
{
  "spreadsheetId": "...",
  "spreadsheetUrl": "...",
  "properties": { "title": "...", "locale": "...", "timeZone": "..." },
  "sheets": [
    {                                      // one element per tab
      "properties": {
        "sheetId": 0, "title": "...", "index": 0,
        "gridProperties": { "rowCount": 1000, "columnCount": 26 }
      },
      "data": [
        {
          "rowData": [
            { "values": [
                { "formattedValue": "...",
                  "userEnteredValue": {...},
                  "effectiveValue": {...} }
            ]}    // an empty cell is {}, a trailing one absent
          ]
        }
      ]
    }
  ],
  "namedRanges": [...]
}
```

Useful `jq` paths:

```jq
.properties.title
.sheets[].properties.title                              # tab names
.sheets[0].data[0].rowData[].values[].formattedValue    # cell strings
.namedRanges[]
```

Delete, on a `write` path:

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

Only `.gsheet.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>.gsheet.json \
   /<path>/owned/<date>_<new>__<id>.gsheet.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 `gsheets` 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 Sheets answers through its own API, so fewer files are read. Integration explains each command.

Command	On Google Sheets
`grep -r`, `rg`	Drive full-text search, for whole words. It can miss words only in non-text values (formulas, the time zone, sheet titles, links and ids).

The Python Google Sheets 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