---
title: Supabase Storage
icon: bolt
description: Mount Supabase Storage as a virtual filesystem.
---
The Supabase resource exposes a Supabase Storage bucket as a virtual
filesystem. It uses the S3-compatible API internally.

## Config

```python
import os

from mirage import MountMode, Workspace
from mirage.resource.supabase import SupabaseConfig, SupabaseResource

config = SupabaseConfig(
    bucket=os.environ["SUPABASE_BUCKET"],
    region=os.environ["SUPABASE_REGION"],
    project_ref="oawrffhlppbtbpnehiif",
    access_key_id=os.environ["SUPABASE_ACCESS_KEY_ID"],
    secret_access_key=os.environ["SUPABASE_SECRET_ACCESS_KEY"],
)
resource = SupabaseResource(config=config)
ws = Workspace({"/supabase": resource}, mode=MountMode.READ)
```

| Field              | Required | Default | Description                          |
| ------------------ | -------- | ------- | ------------------------------------ |
| `bucket`           | yes      |         | Supabase storage bucket name         |
| `region`           | yes      |         | Supabase project region              |
| `project_ref`      | no*      |         | Supabase project reference ID        |
| `endpoint_url`     | no*      |         | Custom S3-compatible endpoint        |
| `access_key_id`    | yes      |         | S3 access key from Supabase settings |
| `secret_access_key`| yes      |         | S3 secret key from Supabase settings |
| `session_token`    | no       |         | Optional session token               |
| `timeout`          | no       | `30`    | Request timeout in seconds           |
| `proxy`            | no       |         | HTTP proxy URL                       |

*Either `project_ref` or `endpoint_url` is required. If `project_ref`
is provided, the endpoint is auto-built as
`https://{project_ref}.storage.supabase.co/storage/v1/s3`.

## Filesystem Layout

```text
/supabase/
  <object-key-path>/
    <file>
```

Object keys map directly to virtual paths.

Example:

```text
/supabase/
  avatars/
    user-001.png
    user-002.png
  documents/
    report.pdf
    data.csv
```

## Cache

Uses `IndexCacheStore` for directory listings with configurable TTL.
File content caching is handled by the workspace.

## Example

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.supabase import SupabaseConfig, SupabaseResource

load_dotenv(".env.development")

config = SupabaseConfig(
    bucket=os.environ["SUPABASE_BUCKET"],
    region=os.environ["SUPABASE_REGION"],
    project_ref="oawrffhlppbtbpnehiif",
    access_key_id=os.environ["SUPABASE_ACCESS_KEY_ID"],
    secret_access_key=os.environ["SUPABASE_SECRET_ACCESS_KEY"],
)
resource = SupabaseResource(config=config)


async def main():
    ws = Workspace({"/supabase": resource}, mode=MountMode.READ)

    r = await ws.execute("ls /supabase/")
    print(await r.stdout_str())

    r = await ws.execute("cat /supabase/documents/data.csv | head -n 10")
    print(await r.stdout_str())

    r = await ws.execute("find /supabase/ -name '*.pdf'")
    print(await r.stdout_str())

    r = await ws.execute("tree -L 2 /supabase/")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())
```

## Shell Commands

| Command         | Notes                                      |
| --------------- | ------------------------------------------ |
| `ls`            | List objects and prefixes                  |
| `cat`           | Read object content                        |
| `head` / `tail` | First/last N lines                         |
| `grep`          | Pattern search                             |
| `wc`            | Line/word/byte counts                      |
| `stat`          | Object metadata (size, modified time)      |
| `find`          | Recursive search with `-name`, `-maxdepth` |
