Supabase Storage

Supabase Storage exposes an S3-compatible API at https://<project-ref>.storage.supabase.co/storage/v1/s3, signed with AWS Signature V4 using Supabase S3 Access Keys (not your project anon / service-role JWT). MIRAGE derives the endpoint from your project_ref automatically and forces path-style URLs.

Credentials

1. Create an S3 access key

Open the Supabase dashboard → your project → Storage → Settings → S3 Access Keys
Click New access key, scope to the bucket(s) you want MIRAGE to see
Copy the Access key ID and Secret access key, the secret is shown once

2. Environment variables

# .env.development
SUPABASE_BUCKET=my-bucket
SUPABASE_REGION=us-east-1
SUPABASE_PROJECT_REF=abcdefghijklmnop
SUPABASE_ACCESS_KEY_ID=...
SUPABASE_SECRET_ACCESS_KEY=...

SUPABASE_REGION is metadata only, Supabase Storage accepts any region string but requires one for SigV4 signing. Use the region you selected when creating the project.

Node (server-side)

pnpm add @struktoai/mirage-node

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

const sb = new SupabaseVFS({
  bucket: process.env.SUPABASE_BUCKET!,
  region: process.env.SUPABASE_REGION!,
  projectRef: process.env.SUPABASE_PROJECT_REF!,
  accessKeyId: process.env.SUPABASE_ACCESS_KEY_ID!,
  secretAccessKey: process.env.SUPABASE_SECRET_ACCESS_KEY!,
})

const ws = new Workspace({ '/bucket/': sb }, { 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` default `true`	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` required	Provider region every request is signed for. Most providers also build their endpoint URL from it unless `endpoint` is set.
`endpoint`	Endpoint URL that replaces the one the provider derives.
`projectRef`	Supabase project reference. It builds the endpoint `https://<projectRef>.storage.supabase.co/storage/v1/s3` unless `endpoint` is set; one of the two is required.

Fields marked secret are redacted in snapshots.

Browser (presigned URLs)

pnpm add @struktoai/mirage-browser

Same pattern as every other S3-compat backend: the browser calls a presignedUrlProvider callback that hits your server, which signs each S3 operation against the Supabase endpoint and returns the URL. The browser fetch()es directly.

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`	Region of the bucket. Most providers derive the endpoint from it; requests go to the host each presigned URL names.
`endpoint`	Endpoint URL that replaces the one the provider derives. 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.
`projectRef`	Supabase project reference. It builds the endpoint `https://<projectRef>.storage.supabase.co/storage/v1/s3` unless `endpoint` is set.

Fields marked secret are redacted in snapshots.

1. Server: sign URLs with the Supabase endpoint

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

const PROJECT_REF = process.env.SUPABASE_PROJECT_REF!
const REGION = process.env.SUPABASE_REGION!

const client = new S3Client({
  region: REGION,
  endpoint: `https://${PROJECT_REF}.storage.supabase.co/storage/v1/s3`,
  forcePathStyle: true,
  credentials: {
    accessKeyId: process.env.SUPABASE_ACCESS_KEY_ID!,
    secretAccessKey: process.env.SUPABASE_SECRET_ACCESS_KEY!,
  },
})
const BUCKET = process.env.SUPABASE_BUCKET!

app.post('/presign/supabase', 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 }) })
})

Supabase requires path-style URLs (forcePathStyle: true). Virtual-hosted style is not supported.

2. Browser: wire it up

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

const sb = new SupabaseVFS({
  bucket: 'my-bucket',
  projectRef: 'abcdefghijklmnop',
  presignedUrlProvider: async (path, op, opts) => {
    const r = await fetch('/presign/supabase', {
      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/': sb }, { mode: MountMode.READ })

3. Configure CORS on the bucket

Supabase Storage’s S3 API respects the bucket’s CORS configuration, which is set in the Supabase dashboard:

Project → Storage → Settings → Policies / CORS configuration
Add http://localhost:5173 (and any production origins)
Methods: GET, PUT, HEAD, DELETE, POST
Headers: *
Exposed headers: ETag, Content-Length, Content-Type, Last-Modified

See the Supabase 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 Supabase Storage mounted at /<path>.

Rendered
Raw

Virtual Filesystem

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

Command	On Supabase Storage
`find`, `du`, `ls -R`, `tree`	One recursive listing

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Supabase Storage

Credentials

1. Create an S3 access key

2. Environment variables

Node (server-side)

Config

Browser (presigned URLs)

Config

1. Server: sign URLs with the Supabase 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

​Credentials

​1. Create an S3 access key

​2. Environment variables

​Node (server-side)

​Config

​Browser (presigned URLs)

​Config

​1. Server: sign URLs with the Supabase 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

Credentials

1. Create an S3 access key

2. Environment variables

Node (server-side)

Config

Browser (presigned URLs)

Config

1. Server: sign URLs with the Supabase 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