Google Cloud Storage

GCS exposes an S3-compatible API when you use HMAC keys, so MIRAGE signs GCS requests with the same AWS Signature V4 used for S3, against the endpoint https://storage.googleapis.com. Credentials (HMAC access key + secret for a service account) are created the same way in both runtimes, see GCS Credentials.

Node (server-side)

pnpm add @struktoai/mirage-node

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

const gcs = new GCSVFS({
  bucket: process.env.GCS_BUCKET!,
  accessKeyId: process.env.GCS_ACCESS_KEY_ID!,
  secretAccessKey: process.env.GCS_SECRET_ACCESS_KEY!,
})

const ws = new Workspace({ '/bucket/': gcs }, { mode: MountMode.READ })
const res = await ws.shell('ls /bucket/')
console.log(res.stdoutText)

Config

Field	Description
`bucket` required	Name of the bucket to mount.
`accessKeyId` secret	Access key ID; set it with `secretAccessKey`. Unset uses the AWS SDK credential chain.
`secretAccessKey` secret	Secret access key paired with `accessKeyId`.
`sessionToken` secret	Session token for temporary credentials, sent with the access key pair.
`profile`	Named profile in the shared AWS config and credentials files that supplies credentials when no access key pair is given.
`forcePathStyle`	Address the bucket in the URL path (`<endpoint>/<bucket>/<key>`) instead of as a subdomain of the endpoint.
`keyPrefix`	Key prefix inside the bucket that the mount treats as its root; keys outside it are not visible. Leading slashes are dropped and a trailing `/` is added.
`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.
`proxy` secret	Proxy URL for every HTTP and HTTPS request to the endpoint.
`region` default `'auto'`	Region requests are signed for; GCS serves every region from one host.
`endpoint` default `'https://storage.googleapis.com'`	Endpoint URL of the S3 interoperability API.

Fields marked secret are redacted in snapshots.

Browser (presigned URLs)

pnpm add @struktoai/mirage-browser

The browser GCSVFS is secret-free, your backend signs each operation using your HMAC keys and hands back a URL. Since GCS accepts AWS Signature V4, the same @aws-sdk/s3-request-presigner code used for S3 works, pointed at the GCS endpoint.

Config

Field	Description
`bucket` required	Name of the bucket to mount.
`presignedUrlProvider` required, secret	Function `(path, operation, options)` that returns a signed URL for each S3 operation; your server signs it, so the browser holds no keys.
`region` default `'auto'`	Region the presigned URLs are signed for; GCS accepts `auto`.
`endpoint` default `'https://storage.googleapis.com'`	Endpoint URL of the GCS XML API. Requests go to the host each presigned URL names; the mount uses it to name its storage location.
`defaultContentType` default `'application/octet-stream'`	`Content-Type` stored with every object the mount writes.
`keyPrefix`	Key prefix the mount treats as its root. The browser can change it before a URL is signed, so enforce the prefix on the signing server.
`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.

Fields marked secret are redacted in snapshots.

1. Server: sign URLs with the GCS endpoint

import {
  CopyObjectCommand,
  DeleteObjectCommand,
  GetObjectCommand,
  HeadObjectCommand,
  ListObjectsV2Command,
  PutObjectCommand,
  S3Client,
} from '@aws-sdk/client-s3'
import { getSignedUrl } from '@aws-sdk/s3-request-presigner'

const client = new S3Client({
  region: 'auto',
  endpoint: 'https://storage.googleapis.com',
  credentials: {
    accessKeyId: process.env.GCS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.GCS_SECRET_ACCESS_KEY!,
  },
})
const BUCKET = process.env.GCS_BUCKET!

app.post('/presign/gcs', async (req, res) => {
  const { path, op, opts } = req.body
  const key = path.replace(/^\/+/, '')
  const ttl = typeof opts?.ttlSec === 'number' ? opts.ttlSec : 300
  let cmd
  switch (op) {
    case 'GET':    cmd = new GetObjectCommand({ Bucket: BUCKET, Key: key }); break
    case 'PUT':    cmd = new PutObjectCommand({ Bucket: BUCKET, Key: key, ContentType: opts?.contentType }); break
    case 'HEAD':   cmd = new HeadObjectCommand({ Bucket: BUCKET, Key: key }); break
    case 'DELETE': cmd = new DeleteObjectCommand({ Bucket: BUCKET, Key: key }); break
    case 'LIST':   cmd = new ListObjectsV2Command({
      Bucket: BUCKET,
      Prefix: opts?.listPrefix,
      Delimiter: opts?.listDelimiter,
      ContinuationToken: opts?.listContinuationToken,
    }); break
    case 'COPY':   cmd = new CopyObjectCommand({
      Bucket: BUCKET,
      Key: key,
      CopySource: `${BUCKET}/${opts?.copySource}`,
    }); break
  }
  res.json({ url: await getSignedUrl(client, cmd, { expiresIn: ttl }) })
})

2. Browser: wire it up

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

const gcs = new GCSVFS({
  bucket: 'my-gcs-bucket',
  presignedUrlProvider: async (path, op, opts) => {
    const r = await fetch('/presign/gcs', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ path, op, opts }),
    })
    const { url } = await r.json()
    return url
  },
})

const ws = new Workspace({ '/bucket/': gcs }, { mode: MountMode.READ })

If you prefer Google’s native signer (Google-provided IAM-signed URLs via @google-cloud/storage’s getSignedUrl), you can use it here too, the presigner contract only cares that the returned URL works with fetch(). Native signing avoids shipping HMAC keys to your backend.

3. Configure CORS on the bucket

GCS rejects S3-flavored PutBucketCors calls, its CORS schema differs. Use either the native XML API (via HMAC keys, same creds your presigner uses) or gsutil cors set. Option A, helper script (no gcloud install): The browser example ships a signer that crafts the GCS-shaped CORS XML and submits it via AWS SigV4 to https://storage.googleapis.com/<bucket>?cors:

cd examples/browser
npx tsx scripts/configure-gcs-cors.ts http://localhost:5173 https://app.example.com

Option B, gsutil:

brew install google-cloud-sdk
gcloud auth login

cat > cors.json <<'EOF'
[
  {
    "origin": ["http://localhost:5173", "https://app.example.com"],
    "method": ["GET", "PUT", "HEAD", "DELETE", "POST"],
    "responseHeader": ["Content-Type", "ETag", "Last-Modified"],
    "maxAgeSeconds": 3000
  }
]
EOF

gsutil cors set cors.json gs://$GCS_BUCKET

GCS’s XML API accepts

<CorsConfig><Cors><Origins>…</Origins><Methods>…</Methods><ResponseHeaders>…</ResponseHeaders><MaxAgeSec>…</MaxAgeSec></Cors></CorsConfig>

. There is no <Headers> / <AllowedHeaders> element, GCS allows all request headers through automatically.

See the GCS VFS docs for the equivalent Python wiring. For write: conditional on this provider, see S3-compatible stores.

VFS.md

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

Rendered
Raw

Virtual Filesystem

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

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>`	Almost all Unix commands.

Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

Path	Limitations
`/<path>`	`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>` | `gcs`, write |

## 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>` | Almost all Unix commands. |

## Limitations of Unix Commands for VFS

Where a path differs from a local filesystem:

| Path | Limitations |
| --- | --- |
| `/<path>` | `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 GCS answers through its own API, so fewer files are read. Integration explains each command.

Command	On GCS
`md5sum`	The object’s ETag, when it is the MD5: a single-part upload, unencrypted or under SSE-S3
`find`, `du`, `ls -R`, `tree`	One recursive listing

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Google Cloud Storage

Node (server-side)

Config

Browser (presigned URLs)

Config

1. Server: sign URLs with the GCS endpoint

2. Browser: wire it up

3. Configure CORS on the bucket

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​Node (server-side)

​Config

​Browser (presigned URLs)

​Config

​1. Server: sign URLs with the GCS endpoint

​2. Browser: wire it up

​3. Configure CORS on the bucket

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

Node (server-side)

Config

Browser (presigned URLs)

Config

1. Server: sign URLs with the GCS endpoint

2. Browser: wire it up

3. Configure CORS on the bucket

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration