nexus-ai-fs 0.9.0

AI-Native Distributed Filesystem Architecture

Nexus

Architecture • PyPI • Examples

An operating system for AI agents.

⚠️ Beta: Nexus is under active development. APIs may change.

What is Nexus?

Nexus is an operating system for AI agents. Like Linux provides processes with a unified interface to hardware (files, sockets, devices), Nexus provides agents with a unified interface to data (files, databases, APIs, SaaS tools) — through syscalls, a virtual filesystem, permissions, and loadable services.

Why an OS, not a framework?

• Kernel with VFS, syscall dispatch, and inode-like metadata — not an application-layer wrapper
• Drivers swapped at config-time via dependency injection (redb, S3, PostgreSQL) — like compiled-in kernel drivers
• Services loaded/unloaded at runtime following the Linux Loadable Kernel Module pattern — not plugins
• Deployment profiles that select which services to include from the same codebase — like Linux distros (Ubuntu, Alpine, BusyBox) built from the same kernel
• Zones as the fundamental isolation and consensus unit (1 zone = 1 Raft group) — like cgroups/namespaces for data

Quick Start

Python SDK

pip install nexus-ai-fs

import nexus

nx = nexus.connect(config={
    "mode": "remote",
    "url": "http://localhost:2026",
    "api_key": "nxk_..."
})

# File operations
nx.sys_write("/workspace/hello.txt", b"Hello, Nexus!")
print(nx.sys_read("/workspace/hello.txt").decode())

# Search across all backends
results = nx.grep("TODO", "/workspace")

# Agent memory
nx.memory.store("User prefers detailed explanations", memory_type="preference")
context = nx.memory.query("What does the user prefer?")

nx.close()

Agent Engine (Embedded)

Run an AI agent directly against a local NexusFS — no server required:

import asyncio
from pathlib import Path
from pydantic import SecretStr

from nexus.backends.local import LocalBackend
from nexus.core.config import PermissionConfig
from nexus.factory import create_nexus_fs
from nexus.storage.raft_metadata_store import RaftMetadataStore
from nexus.storage.record_store import SQLAlchemyRecordStore

from nexus.bricks.llm.config import LLMConfig
from nexus.bricks.llm.provider import LiteLLMProvider
from nexus.system_services.agent_runtime.process_manager import ProcessManager
from nexus.system_services.agent_runtime.types import AgentProcessConfig, TextDelta
from nexus.contracts.llm_types import Message, MessageRole


async def main():
    # 1. Bootstrap NexusFS (local storage, no server)
    data = Path("/tmp/nexus-agent")
    data.mkdir(exist_ok=True)
    nx = create_nexus_fs(
        backend=LocalBackend(root_path=str(data / "files")),
        metadata_store=RaftMetadataStore.embedded(str(data / "raft")),
        record_store=SQLAlchemyRecordStore(),
        permissions=PermissionConfig(enforce=False),
    )

    # 2. Create LLM provider
    llm = LiteLLMProvider(LLMConfig(
        model="claude-haiku-4-5-20251001",
        api_key=SecretStr("sk-ant-..."),  # your API key
    ))

    # 3. Spawn agent and chat
    pm = ProcessManager(vfs=nx, llm_provider=llm)
    proc = await pm.spawn("user1", "default", config=AgentProcessConfig(
        name="my-agent",
        tools=("read_file", "write_file", "grep", "glob"),
    ))

    async for event in pm.resume(
        proc.pid,
        Message(role=MessageRole.USER, content="List the files in /default"),
    ):
        if isinstance(event, TextDelta):
            print(event.text, end="", flush=True)
    print()

    # Cleanup
    await pm.terminate(proc.pid)
    await llm.cleanup()
    nx.close()

asyncio.run(main())

CLI

pip install nexus-ai-fs

export NEXUS_URL="http://localhost:2026"
export NEXUS_API_KEY="nxk_..."

nexus write /workspace/hello.txt "Hello, Nexus!"
nexus cat /workspace/hello.txt
nexus grep "TODO" /workspace
nexus memory store "Important fact" --type fact

Architecture

┌──────────────────────────────────────────────────────────────┐
│  SERVICES (user space)                                       │
│  Loadable at runtime. ReBAC, Auth, Agents, Search, Skills…   │
└──────────────────────────────────────────────────────────────┘
                          ↓ protocol interface
┌──────────────────────────────────────────────────────────────┐
│  KERNEL                                                      │
│  VFS, MetastoreABC, ObjectStoreABC, syscall dispatch,        │
│  pipes, lock manager, three-phase dispatch (LSM hooks)       │
└──────────────────────────────────────────────────────────────┘
                          ↓ dependency injection
┌──────────────────────────────────────────────────────────────┐
│  DRIVERS                                                     │
│  redb, S3, PostgreSQL, Dragonfly, LocalDisk, gRPC…           │
└──────────────────────────────────────────────────────────────┘

Tier	Linux Analogue	Nexus	Swap time
Kernel	vmlinuz (scheduler, mm, VFS)	VFS, MetastoreABC, syscall dispatch	Never
Drivers	Compiled-in drivers (=y)	redb, S3, PostgreSQL, SearchBrick	Config-time (DI)
Services	Loadable kernel modules (insmod/rmmod)	23 protocols — ReBAC, Mount, Auth, Agents, …	Runtime

Invariant: Services depend on kernel interfaces, never the reverse. The kernel operates with zero services loaded.

Four Storage Pillars

Storage is abstracted by capability (access pattern + consistency guarantee), not by domain:

Pillar	ABC	Capability	Kernel role
Metastore	MetastoreABC	Ordered KV, CAS, prefix scan, optional Raft SC	Required — sole kernel init param
ObjectStore	ObjectStoreABC	Streaming blob I/O, petabyte scale	Interface only — mounted dynamically
RecordStore	RecordStoreABC	Relational ACID, JOINs, vector search	Services only — optional
CacheStore	CacheStoreABC	Ephemeral KV, Pub/Sub, TTL	Optional — defaults to NullCacheStore

Deployment Profiles (Distros)

Same kernel, different service sets — like Linux distros:

Profile	Linux Analogue	Target	Services
minimal	initramfs	Bare minimum	1
embedded	BusyBox	MCU, WASM (<1 MB)	2
lite	Alpine	Pi, Jetson, mobile	8
full	Ubuntu Desktop	Desktop, laptop	21
cloud	Ubuntu Server	k8s, serverless	22 (all)
remote	NFS client	Client-side proxy	0

See Kernel Architecture for the full design.

Examples

Framework	Description	Location
CrewAI	Multi-agent collaboration	examples/crewai/
LangGraph	Permission-based workflows	examples/langgraph_integration/
Claude SDK	ReAct agent pattern	examples/claude_agent_sdk/
OpenAI Agents	Multi-tenant with memory	examples/openai_agents/
Google ADK	Agent Development Kit	examples/google_adk/
CLI	40+ shell demos	examples/cli/

Contributing

git clone https://github.com/nexi-lab/nexus.git
cd nexus
pip install -e ".[dev]"
pre-commit install
pytest tests/

License

© 2025 Nexi Labs, Inc. Licensed under Apache License 2.0 — see LICENSE for details.