Alibaba OSS

The Aliyun VFS is a thin wrapper over the S3 VFS. It maps an AliyunConfig to an S3Config and reuses the exact same backend, commands, and behavior as S3, it just derives the right OSS endpoint from region. Uses aioboto3 against Alibaba OSS’s S3-compatible API. The endpoint is computed from region as s3.oss-<region>.aliyuncs.com (e.g. s3.oss-cn-hangzhou.aliyuncs.com). Note the s3. prefix: this is the S3-compatible host, distinct from the native oss-<region>.aliyuncs.com. Pass endpoint_url to override. Install the extra:

pip install "mirage-ai[s3]"

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.aliyun import AliyunConfig, AliyunVFS

config = AliyunConfig(
    bucket=os.environ["OSS_BUCKET"],
    region=os.environ.get("OSS_REGION", "cn-hangzhou"),
    access_key_id=os.environ["OSS_ACCESS_KEY_ID"],
    secret_access_key=os.environ["OSS_ACCESS_KEY_SECRET"],
    # Optional:
    # endpoint_url="https://s3.oss-cn-hangzhou.aliyuncs.com",
    # timeout=30,
    # proxy="http://proxy:8080",
)
vfs = AliyunVFS(config)
ws = Workspace({"/data": 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` required	Provider region every request is signed for. Most providers also build their endpoint URL from it unless `endpoint_url` is set.
`endpoint_url`	Endpoint URL that replaces the one the provider derives.
`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 `False`	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 Alibaba OSS mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`aliyun`, 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>` | `aliyun`, 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.aliyun import AliyunConfig, AliyunVFS

load_dotenv(".env.development")

config = AliyunConfig(
    bucket=os.environ["OSS_BUCKET"],
    region=os.environ.get("OSS_REGION", "cn-hangzhou"),
    access_key_id=os.environ["OSS_ACCESS_KEY_ID"],
    secret_access_key=os.environ["OSS_ACCESS_KEY_SECRET"],
)
vfs = AliyunVFS(config)


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

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

    r = await ws.shell("tree /data/")
    print(await r.stdout_str())


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

Notes

Aliyun 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 Alibaba OSS Setup.

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

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