Ceph (Rados Gateway)

The Ceph VFS is a thin wrapper over the S3 VFS. It maps a CephConfig to an S3Config and reuses the exact same backend, commands, and behavior as S3, it just points at your Ceph Rados Gateway endpoint_url and uses path-style addressing by default. Ceph RGW is self-hosted, so endpoint_url is required (there is no region-derived host). Uses aioboto3 against the gateway’s S3-compatible API. Install the extra:

pip install "mirage-ai[s3]"

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.ceph import CephConfig, CephVFS

config = CephConfig(
    bucket=os.environ["CEPH_BUCKET"],
    endpoint_url=os.environ["CEPH_ENDPOINT_URL"],
    access_key_id=os.environ["CEPH_ACCESS_KEY_ID"],
    secret_access_key=os.environ["CEPH_SECRET_ACCESS_KEY"],
    # Optional:
    # region="us-east-1",   # default
    # path_style=True,      # default
    # timeout=30,
    # proxy="http://proxy:8080",
)
vfs = CephVFS(config)
ws = Workspace({"/ceph": vfs}, mode=MountMode.READ)

Both READ and WRITE modes are supported.

Field	Description
`timeout` default `30`	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.
`bucket` required	Name of the bucket to mount.
`region` default `'us-east-1'`	Region requests are signed for; the gateway’s endpoint does not depend on it.
`endpoint_url` required	URL of the self-hosted S3 gateway, such as `http://localhost:9000`.
`access_key_id` secret	Access key ID; set it with `secret_access_key`. Unset uses the AWS credential chain.
`secret_access_key` secret	Secret access key paired with `access_key_id`.
`session_token` secret	Session token for temporary credentials, sent with the access key pair.
`aws_profile`	Named profile in the shared AWS config and credentials files that supplies credentials when no access key pair is given.
`path_style` default `True`	Address the bucket in the URL path (`<endpoint>/<bucket>/<key>`) instead of as a subdomain of the endpoint.
`key_prefix`	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.
`proxy` secret	Proxy URL for every HTTP and HTTPS request to the endpoint.

Fields marked secret are redacted in snapshots. For write: conditional on this provider, see S3-compatible stores.

VFS.md

The VFS.md an agent reads with Ceph (Rados Gateway) mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`ceph`, 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>` | `ceph`, 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.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.vfs.ceph import CephConfig, CephVFS

load_dotenv(".env.development")

config = CephConfig(
    bucket=os.environ["CEPH_BUCKET"],
    endpoint_url=os.environ["CEPH_ENDPOINT_URL"],
    access_key_id=os.environ["CEPH_ACCESS_KEY_ID"],
    secret_access_key=os.environ["CEPH_SECRET_ACCESS_KEY"],
)
vfs = CephVFS(config)


async def main() -> None:
    ws = Workspace({"/ceph/": vfs}, mode=MountMode.READ)

    r = await ws.shell("ls /ceph/")
    print(await r.stdout_str())

    r = await ws.shell("find /ceph/ -name '*.json'")
    print(await r.stdout_str())


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

Notes

Ceph registers under its own VFSName and routes through the same core/s3 implementation, so the full S3 shell-command set applies. See the S3 VFS for the complete command reference, range reads, streaming, and the index cache fast path.
For credential setup, see Ceph Setup.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Ceph (Rados Gateway)

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Example

Notes

​Config

​VFS.md

​Virtual Filesystem

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Example

​Notes

Config

VFS.md

Virtual Filesystem

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Example

Notes