ContextQMD
Back to Mastra

Reference: GCSFilesystem | Workspace

docs/src/content/en/reference/workspace/gcs-filesystem.mdx

2025-12-186.0 KB
Original Source

GCSFilesystem

Stores files in Google Cloud Storage.

:::info

For interface details, see WorkspaceFilesystem Interface.

:::

Installation

bash
npm install @mastra/gcs

Usage

Add a GCSFilesystem to a workspace and assign it to an agent:

typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'

const workspace = new Workspace({
  filesystem: new GCSFilesystem({
    bucket: 'my-gcs-bucket',
    projectId: 'my-project-id',
    credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
  }),
})

const agent = new Agent({
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-6',
  workspace,
})

Using Application Default Credentials

If running on Google Cloud or with gcloud CLI configured, you can omit credentials:

typescript
import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  // Uses Application Default Credentials automatically
})

Application Default Credentials (ADC) automatically discovers credentials in this order:

  1. GOOGLE_APPLICATION_CREDENTIALS environment variable (path to a service account key file)
  2. Default service account when running on GCP (Compute Engine, Cloud Run, GKE, etc.)
  3. User credentials from gcloud auth application-default login (for local development)

Using a Key File Path

You can also pass a path to a service account key file:

typescript
import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  projectId: 'my-project-id',
  credentials: '/path/to/service-account-key.json',
})

Constructor parameters

<PropertiesTable content={[ { name: 'bucket', type: 'string', description: 'GCS bucket name', }, { name: 'projectId', type: 'string', description: 'GCS project ID. Required when using service account credentials.', isOptional: true, }, { name: 'credentials', type: 'object | string', description: 'Service account key JSON object or path to key file. If not provided, uses Application Default Credentials.', isOptional: true, }, { name: 'prefix', type: 'string', description: 'Optional prefix for all keys (acts like a subdirectory)', isOptional: true, }, { name: 'id', type: 'string', description: 'Unique identifier for this filesystem instance', isOptional: true, defaultValue: 'Auto-generated', }, { name: 'displayName', type: 'string', description: 'Human-friendly display name for the UI', isOptional: true, }, { name: 'icon', type: 'FilesystemIcon', description: 'Icon identifier for the UI', isOptional: true, }, { name: 'description', type: 'string', description: 'Short description of this filesystem for the UI', isOptional: true, }, { name: 'readOnly', type: 'boolean', description: 'When true, all write operations are blocked', isOptional: true, defaultValue: 'false', }, { name: 'endpoint', type: 'string', description: 'Custom API endpoint URL. Used for local development with emulators.', isOptional: true, }, ]} />

Properties

<PropertiesTable content={[ { name: 'id', type: 'string', description: 'Filesystem instance identifier', }, { name: 'name', type: 'string', description: "Provider name ('GCSFilesystem')", }, { name: 'provider', type: 'string', description: "Provider identifier ('gcs')", }, { name: 'bucket', type: 'string', description: 'The GCS bucket name', }, { name: 'readOnly', type: 'boolean | undefined', description: 'Whether the filesystem is in read-only mode', }, ]} />

Methods

GCSFilesystem implements the WorkspaceFilesystem interface, providing all standard filesystem methods:

  • readFile(path, options?) - Read file contents
  • writeFile(path, content, options?) - Write content to a file
  • appendFile(path, content) - Append content to a file
  • deleteFile(path, options?) - Delete a file
  • copyFile(src, dest, options?) - Copy a file
  • moveFile(src, dest, options?) - Move or rename a file
  • mkdir(path, options?) - Create a directory
  • rmdir(path, options?) - Remove a directory
  • readdir(path, options?) - List directory contents
  • exists(path) - Check if a path exists
  • stat(path) - Get file or directory metadata

init()

Initialize the filesystem. Verifies bucket access and credentials.

typescript
await filesystem.init()

getInfo()

Returns metadata about this filesystem instance.

typescript
const info = filesystem.getInfo()
// { id: '...', name: 'GCSFilesystem', provider: 'gcs', status: 'ready' }

getMountConfig()

Returns the mount configuration for sandboxes that support mounting this filesystem type.

typescript
const config = filesystem.getMountConfig()
// { type: 'gcs', bucket: 'my-bucket', ... }

Mounting in E2B sandboxes

GCSFilesystem can be mounted into E2B sandboxes, making the bucket accessible as a local directory:

typescript
import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new GCSFilesystem({
      bucket: 'my-gcs-bucket',
      projectId: 'my-project-id',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})

See E2BSandbox reference for more details on mounting.