Google Calendar

The Google Calendar VFS mounts every calendar the account can see as a directory of date buckets, with one JSON file per event. It uses the same OAuth credentials as the other Google mounts; enable the Google Calendar API and its scope as described in Google Workspace Setup. For SDK guides, see Google Calendar (Python) and Google Calendar (TypeScript).

Connect

Python
TypeScript
YAML

import asyncio
import os

from mirage import MountMode, Workspace
from mirage.vfs.gcal import GCalConfig, GCalVFS


async def main() -> None:
    config = GCalConfig(
        client_id=os.environ["GOOGLE_CLIENT_ID"],
        client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
        refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
    )
    ws = Workspace({"/gcal": GCalVFS(config)}, mode=MountMode.READ)
    result = await ws.shell("ls /gcal/primary")
    print(await result.stdout_str(), end="")
    await ws.close()


asyncio.run(main())

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

const ws = new Workspace({
  '/gcal': new GCalVFS({
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    refreshToken: process.env.GOOGLE_REFRESH_TOKEN!,
    bucketDays: 1,
  }),
}, { mode: MountMode.READ })
const result = await ws.shell('ls /gcal/primary')
process.stdout.write(result.stdoutText)
await ws.close()

mounts:
  /gcal:
    vfs: gcal
    mode: read
    config:
      client_id: ${GOOGLE_CLIENT_ID}
      client_secret: ${GOOGLE_CLIENT_SECRET}
      refresh_token: ${GOOGLE_REFRESH_TOKEN}

Browse events

/gcal/
  primary/
    calendar.json
    <YYYY-MM-DD>/
      <event-id>__<HHMM-HHMM>_<title>.gcal.json
  <name>__<calendar-id>/
    ...

The primary calendar is always primary; every other calendar directory ends in __<calendar-id>. Each date directory holds the events of one day by default; set bucket_days to 7 or 30 for 7-day or 30-day buckets. Without start_time or end_time, a calendar lists all of its history up to 90 days after today. Use ls and date globs such as ls /gcal/primary/2026-11-* to find events, then cat or jq to read the Calendar API payload. On a mount in write mode, rm an event file to delete that event for every attendee; that needs the owner or writer role on its calendar. Create and edit events with the gws calendar CLI.

Getting Started

Examples

Agents

VFS

Integration

CLIs

Mirage Shell

Agent Profiles

Policy

Runtimes

Infrastructure

Configuration

Notifications

Help

Google Calendar

Connect

Browse events

​Connect

​Browse events

Connect

Browse events