Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt

Use this file to discover all available pages before exploring further.

The R2 resource exposes a Cloudflare R2 bucket as a virtual filesystem. It uses the S3-compatible API internally. For credential setup, see R2 Setup.

​
Config

import os

from mirage import MountMode, Workspace
from mirage.resource.r2 import R2Config, R2Resource

config = R2Config(
    bucket=os.environ["R2_BUCKET"],
    account_id=os.environ["R2_ACCOUNT_ID"],
    access_key_id=os.environ["R2_ACCESS_KEY_ID"],
    secret_access_key=os.environ["R2_SECRET_ACCESS_KEY"],
)
resource = R2Resource(config=config)
ws = Workspace({"/r2": resource}, mode=MountMode.READ)
FieldRequiredDefaultDescription
bucketyesR2 bucket name
account_idno*Cloudflare account ID
endpoint_urlno*Custom endpoint URL
access_key_idnoR2 API token access key
secret_access_keynoR2 API token secret key
aws_profilenoAWS profile name (alternative auth)
regionnoautoRegion (R2 defaults to auto)
timeoutno30Request timeout in seconds
proxynoHTTP proxy URL
*Either account_id or endpoint_url is required. If account_id is provided, the endpoint is auto-built as https://{account_id}.r2.cloudflarestorage.com.

​
Filesystem Layout

/r2/
  <object-key-path>/
    <file>
Object keys map directly to virtual paths. Example: 
/r2/
  assets/
    logo.png
    style.css
  data/
    export.parquet
    metrics.csv
Columnar files (.parquet, .orc, .feather) return formatted tables when read via cat.

​
Cache

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

​
Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.r2 import R2Config, R2Resource

load_dotenv(".env.development")

config = R2Config(
    bucket=os.environ["R2_BUCKET"],
    account_id=os.environ["R2_ACCOUNT_ID"],
    access_key_id=os.environ["R2_ACCESS_KEY_ID"],
    secret_access_key=os.environ["R2_SECRET_ACCESS_KEY"],
)
resource = R2Resource(config=config)


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

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

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

    # Parquet files render as formatted tables
    r = await ws.execute("cat /r2/data/export.parquet")
    print(await r.stdout_str())

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


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

​
Shell Commands

CommandNotes
lsList objects and prefixes
catRead object content (tables for columnar)
head / tailFirst/last N lines
grep / rgPattern search
jqQuery JSON objects
wcLine/word/byte counts
statObject metadata (size, modified time)
findRecursive search with -name, -maxdepth
treeDirectory tree view