SeaweedFS

The SeaweedFS VFS is a thin wrapper over the S3 VFS. It maps a SeaweedFSConfig to an S3Config and reuses the exact same backend, commands, and behavior as S3, it just points at your SeaweedFS S3 gateway endpoint_url and uses path-style addressing by default. SeaweedFS exposes an S3-compatible gateway (default port 8333), so endpoint_url is required (there is no region-derived host). Uses aioboto3 against the SeaweedFS S3 API. Install the extra:

pip install "mirage-ai[s3]"

Config

import os

from mirage import MountMode, Workspace
from mirage.vfs.seaweedfs import SeaweedFSConfig, SeaweedFSVFS

config = SeaweedFSConfig(
    bucket=os.environ["SEAWEEDFS_BUCKET"],
    endpoint_url=os.environ.get("SEAWEEDFS_ENDPOINT", "http://localhost:8333"),
    access_key_id=os.environ["SEAWEEDFS_ACCESS_KEY"],
    secret_access_key=os.environ["SEAWEEDFS_SECRET_KEY"],
    # Optional:
    # region="us-east-1",   # default
    # path_style=True,      # default; SeaweedFS uses path-style addressing
    # timeout=30,
    # proxy="http://proxy:8080",
)
vfs = SeaweedFSVFS(config)
ws = Workspace({"/seaweedfs": vfs}, mode=MountMode.WRITE)

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 SeaweedFS mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`seaweedfs`, 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>` | `seaweedfs`, 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.seaweedfs import SeaweedFSConfig, SeaweedFSVFS

load_dotenv(".env.development")

config = SeaweedFSConfig(
    bucket=os.environ.get("SEAWEEDFS_BUCKET", "mirage-demo"),
    endpoint_url=os.environ.get("SEAWEEDFS_ENDPOINT", "http://localhost:8333"),
    access_key_id=os.environ.get("SEAWEEDFS_ACCESS_KEY", "any"),
    secret_access_key=os.environ.get("SEAWEEDFS_SECRET_KEY", "any"),
)
vfs = SeaweedFSVFS(config)


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

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

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

    r = await ws.shell("cat /seaweedfs/data/config.json")
    print(await r.stdout_str())


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

Notes

SeaweedFS registers under its own VFSName and routes through the same core/s3 implementation, so the full S3 shell-command set applies (ls, cat, head, tail, grep, rg, wc, find, tree, jq, stat). See the S3 VFS for the complete command reference, range reads, streaming, and the index cache fast path.
Blaxel Agent Drive is backed by SeaweedFS. To mount a drive’s S3 gateway, point endpoint_url at the drive’s s3Url and supply credentials for it.
For credential setup, see SeaweedFS 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