nexus-fs

Unified filesystem abstraction for cloud storage. Mount S3, GCS, Google Workspace, and local storage with two lines of Python.

import nexus.fs

fs = nexus.fs.mount_sync("s3://my-bucket", "local://./data")
content = fs.read("/s3/my-bucket/README.md")

Install

pip install nexus-fs            # core (local only)
pip install nexus-fs[s3]        # + Amazon S3
pip install nexus-fs[gcs]       # + Google Cloud Storage
pip install nexus-fs[gdrive]    # + Google Drive
pip install nexus-fs[fsspec]    # + fsspec/pandas/dask integration
pip install nexus-fs[tui]       # + interactive TUI playground
pip install nexus-fs[all]       # everything

Quick Start

Async

import asyncio
import nexus.fs

async def main():
    fs = await nexus.fs.mount("s3://my-bucket", "local://./data")
    await fs.write("/local/data/hello.txt", b"Hello!")
    content = await fs.read("/local/data/hello.txt")
    print(content)

asyncio.run(main())

Sync

import nexus.fs

fs = nexus.fs.mount_sync("local://./data")
fs.write("/local/data/hello.txt", b"Hello!")
print(fs.read("/local/data/hello.txt"))

Connectors (Google Workspace, GitHub, Slack, etc.)

import nexus.fs

fs = nexus.fs.mount_sync("gws://sheets", "gws://docs")
# Uses gws CLI under the hood — no server needed

Prerequisite: gws:// mounts require the gws CLI to be installed and authenticated. Other connectors (GitHub, Slack) require OAuth credentials configured via environment variables — see nexus-fs doctor for diagnostics.

API

TUI Playground

pip install nexus-fs[tui]
nexus-fs playground s3://my-bucket local://./data

CLI

nexus-fs mount s3://my-bucket
nexus-fs mount list
nexus-fs mount test s3://my-bucket
nexus-fs unmount s3://my-bucket

Note: The TUI uses direct backend access for low-latency browsing. File operation semantics in the playground may differ from the library API (e.g., metadata fields, error messages). The library API (mount() / mount_sync()) is the authoritative interface. TUI/library unification is planned for a future release.

State Directory

nexus-fs stores runtime state (metadata DB, mount config) in a platform-specific directory. This state is a cache — it can be safely deleted and will be recreated on the next mount() call.

Override with the NEXUS_FS_STATE_DIR environment variable.

Persistent secrets (OAuth tokens, encryption keys) are stored separately under ~/.nexus/ with restricted permissions (0700). Override with NEXUS_FS_PERSISTENT_DIR.

Concurrency: nexus-fs is designed for single-process use per state directory. To run multiple independent instances, set a different NEXUS_FS_STATE_DIR for each process.

Relationship to nexus-ai-fs

nexus-fs is the slim standalone cloud storage package (~16 dependencies). nexus-ai-fs is the full Nexus filesystem/context plane (~100+ dependencies) that includes server, bricks, gRPC, federation, and more.

Both packages install into the nexus Python namespace. Do not install both in the same environment — they will conflict. Choose one:

• pip install nexus-fs — lightweight cloud storage only
• pip install nexus-ai-fs — full Nexus system (includes all nexus-fs functionality)

License

Apache-2.0