Distributed VFS for multi-agent systems

The infrastructure layer that decides how agents coexist — storage, communication, permissions, coordination.

Documentation · Quickstart · Examples · PyPI · nexus-fs · TUI · Roadmap

---

Why Nexus exists

The hard problem isn't making one agent work. It's making many agents work together reliably across nodes.

Agent harnesses (LangGraph, CrewAI, AutoGen) decide what agents do — tool calls, chains, memory loops. Nexus is the layer underneath that handles how agents coexist: shared storage, permission boundaries, inter-agent messaging, distributed coordination. A distributed VFS kernel — like Linux for AI agents — providing the primitives every harness needs:

Steering engineering — infrastructure that sets boundaries and rules so agents operate safely at scale:

• Permission boundaries (ReBAC) — agents only touch what they're allowed to
• Data sovereignty (zone isolation, local-first, encrypted-at-rest) — data never leaves its zone without explicit policy; cross-zone computation uses privacy-preserving protocols
• IPC primitives (DT_PIPE ~0.5us, DT_STREAM append-only log) — zero-copy inter-agent messaging
• Process isolation (ProcessTable, workspace boundaries) — agent crashes don't cascade
• Distributed coordination (Raft consensus, advisory locks) — multi-node without split-brain

Context engineering — infrastructure that gives agents the right information at the right time:

• Unified VFS namespace — all data under one path tree, not scattered APIs
• Semantic search (BM25S + pgvector + section-aware grep) — precise context retrieval
• CAS dedup + content chunking — efficient storage and retrieval at scale
• Federation reads — transparent cross-node data access, agents don't need to know where data lives

Production distributed topology — a full IT infrastructure for agent organizations:

Node role	Profile	What it does
Hub	full	Central server — Postgres, Dragonfly, all 35+ bricks, auth, search
Worker	sandbox	Agent execution sandbox — SQLite + BM25S, zero external deps
Gateway	remote	Thin RPC client — zero local storage, routes to hub
Auditor	cluster + audit	Centralized audit log — every operation across all nodes
Federation peer	cloud	Full + Raft consensus + multi-tenant — spans data centers
Edge	lite / embedded	Pi, Jetson, MCU — local-first with federation sync

These compose like corporate IT: gateway nodes front the traffic, hubs serve the workload, workers run agents in isolation, auditors watch everything, federation peers replicate across regions. One binary, different profiles.

One interface. Start embedded in a single Python process, scale to a federated cluster across data centers. No code changes.

Built by SudoWork — we focus on making agents deliver quality work, with token economy.

Architecture

Deployment stack

graph TD
    subgraph Applications
        SW[sudowork]
        CD[Codex Desktop]
        CA[custom apps]
    end

    subgraph Agent_Harness ["Agent Harness (open ecosystem, hook-compatible)"]
        SC[sudocode / sudocode-host]
        GC[Gemini CLI]
        CX[Codex CLI]
        AH[any agent]
    end

    subgraph Infra ["Infra Layer (one per node)"]
        NX["NEXUS (distributed VFS: storage, IPC, permissions, coordination, data sovereignty)"]
        SR["SUDOROUTER (unified LLM access + confidential computing: Claude, GPT, Gemini, local models)"]
    end

    SW --> SC
    CD --> CX
    CA --> AH
    SC --> NX
    GC --> NX
    CX --> NX
    AH --> NX
    SC -.->|direct| SR
    NX -->|as backend| SR

Loading

Agents don't need to integrate Nexus directly. The hook layer (Node.js fs interception / Python open patching) transparently routes any agent's file I/O through Nexus syscalls — the agent gets federation, A2A, collaboration, approval hooks, and security for free without changing a line of code. SudoRouter provides unified model access (any agent, any model, no provider lock-in) with confidential computing for privacy-preserving inference and training; agents reach it either through Nexus (as a mounted backend) or directly.

Nexus internals

graph TD
    subgraph Bricks ["Bricks (runtime-loadable, 35+)"]
        B[ReBAC · Auth · Agents · Search · MCP · Pay · Governance · 25+ more]
    end

    subgraph Kernel ["Kernel (pure Rust, ~5 MB binary)"]
        K[VFS · Syscall dispatch · CAS · Pipes · Streams · Locks · FileWatcher · Permission gate · Raft]
    end

    subgraph Drivers ["Drivers (hot-swappable)"]
        D[redb · PostgreSQL · S3 · GCS · Dragonfly · BM25S · SudoRouter · gRPC]
    end

    B -->|protocol interface| K
    K -->|dependency injection| D

Loading

Kernel is pure Rust — a ~5 MB static binary (nexusd-cluster) with 14 syscalls and zero Python dependency. Never changes.

Drivers swap at mount time via sys_setattr. Hot-plug any storage or LLM backend without restart.

Bricks mount and unmount at runtime via service_enlist / service_swap — like insmod/rmmod for an AI filesystem.

Services (bricks) — 30 runtime-loadable capabilities

Category	Services
Security & Privacy	ReBAC (Zanzibar-style permissions), Auth (API key, OAuth, mTLS), Delegation (SSH-style scoped access), Identity (DID + verifiable credentials), Encrypted Storage (AES-256-GCM), Zone data isolation
Search & Context	Keyword search (BM25S), Semantic search (pgvector), Section-aware grep, Content parsing (50+ formats via pdf-inspector), Catalog (schema extraction)
Agent Runtime	Agent Registry, Agent Runtime (subprocess + managed), IPC (DT_PIPE + DT_STREAM), Sandbox (Docker isolation), Task Manager
Collaboration	Share Links (capability URLs), Workspace boundaries, A2A Protocol, MCP (30+ tools, mount external MCP servers)
Data Management	Versioning, Snapshots (atomic multi-file), Portability (import/export), Memory (persistent + consolidation), Access Manifests
Operations	Pay (credit ledger + policies), Governance (fraud detection, trust scores), Workflows (trigger/condition/action), Observability, Scheduler (fair-share + priority)
Integration	Discovery (dynamic tool selection), Upload (TUS resumable), Federation (cross-zone Raft)

Drivers — 15 hot-swappable backends

Category	Drivers
Storage	PathLocal (filesystem), CAS-Local (content-addressed), S3, GCS, Remote (gRPC proxy)
Database	PostgreSQL (pgvector), redb (embedded ordered KV)
Cache	Dragonfly / Redis
Search	BM25S (keyword), Zoekt (code search, optional)
Connectors	Gmail, Google Drive, Slack, X/Twitter, Hacker News, Nostr, CLI
LLM	SudoRouter (unified: Claude, GPT, Gemini, local models)

Get started

Run Nexus

Two ways to start a Nexus node — nexus (managed Docker stack) or nexusd (direct daemon):

# Managed stack (Nexus + Postgres + Dragonfly via Docker)
pip install nexus-ai-fs
nexus init --preset shared
nexus up
eval $(nexus env)

# Direct daemon (single process, no Docker)
nexusd --port 2026 --data-dir ./nexus-data

Use Nexus

Once running, interact via SDK, CLI, or TUI:

# SDK
import asyncio, nexus


async def main():
    nx = await nexus.connect()  # connects to running nexusd
    await nx.write("/hello.txt", b"hello world")
    print((await nx.read("/hello.txt")).decode())
    nx.close()


asyncio.run(main())

# CLI (RPC client — talks to running nexusd via gRPC)
nexus write /hello.txt "hello world"
nexus cat /hello.txt
nexus ls /
nexus grep "TODO" -f "**/*.py"
nexus search query "hello" --mode hybrid

# TUI
bunx @nexus-ai-fs/tui                                        # connects to localhost:2026
bunx @nexus-ai-fs/tui --url http://remote:2026 --api-key KEY # connect to remote

Embedded (no daemon)

For scripts and notebooks — in-process, zero infrastructure:

import asyncio, nexus


async def main():
    nx = await nexus.connect(config={"data_dir": "./my-data"})
    await nx.write("/notes/meeting.md", b"# Q3 Planning\n- Ship Nexus 1.0")
    print((await nx.read("/notes/meeting.md")).decode())
    nx.close()


asyncio.run(main())

What you get

Capability	What it does	How agents use it
Filesystem	POSIX-style read/write/mkdir/ls with CAS dedup	Shared workspace — no more temp files
Versioning	Every write creates an immutable version	Rollback mistakes, diff changes, audit trails
Snapshots	Atomic multi-file transactions	Commit or rollback a batch of changes together
Search	BM25S + semantic + hybrid + section-aware grep	Find anything by content, meaning, or structure
Memory	Persistent agent memory with consolidation + versioning	Remember across runs and sessions
Delegation	SSH-style agent-to-agent permission narrowing	Safely sub-delegate work with scoped access
ReBAC	Relationship-based access control (Google Zanzibar model)	Fine-grained per-file, per-agent permissions
MCP	Mount external MCP servers, expose Nexus as 30+ MCP tools	Bridge any tool ecosystem
Workflows	Trigger / condition / action pipelines	Automate file processing, notifications, etc.
Governance	Fraud detection, collusion rings, trust scores	Safety rails for autonomous agent fleets
Pay	Credit ledger with reserves, policies, approvals	Metered compute for multi-tenant deployments
IPC	DT_PIPE (FIFO) + DT_STREAM (append-only log)	Sub-microsecond inter-agent messaging
Federation	Multi-zone Raft consensus with mTLS TOFU	Span data centers without a central coordinator
Data Sovereignty	Zone isolation, local-first, AES-256-GCM encrypted storage	Data stays in its zone; cross-zone ops use privacy-preserving computation
Sandbox	Docker-backed execution environments	Isolated code execution per agent

See Services and Drivers for the full categorized list.

Framework integrations

Every major agent framework works out of the box:

Framework	What the example shows	Link
Claude Agent SDK	ReAct agent with Nexus as tool provider	examples/claude_agent_sdk/
OpenAI Agents	Multi-tenant agents with shared memory	examples/openai_agents/
LangGraph	Permission-scoped workflows	examples/langgraph_integration/
CrewAI	Multi-agent collaboration on shared files	examples/crewai/
Google ADK	Agent Development Kit integration	examples/google_adk/
E2B	Cloud sandbox execution	examples/e2b/
CLI	40+ shell demos covering every feature	examples/cli/

Deployment

Two binaries, inspired by the docker/dockerd convention:

Binary	What	Lifecycle
nexusd	Node daemon — manages storage, serves gRPC/HTTP, participates in federation	Long-running (SIGTERM to stop)
nexus	CLI client — file ops, search, admin, status via gRPC to a running nexusd	Invocation-style (exits when done)

Running nexusd

# Direct daemon
nexusd --port 2026 --data-dir /var/lib/nexus

# With explicit profile + federation
nexusd --profile full --host 0.0.0.0 --join peer1:2026 --zone us-west

# Managed Docker stack (Nexus + Postgres + Dragonfly)
nexus init --preset shared && nexus up

nexus init presets

Preset	Services	Auth	Use case
local	None (embedded)	None	Single-process scripts, notebooks
shared	Nexus + Postgres + Dragonfly	Static API key	Team dev, multi-agent staging
demo	Same as shared	Database-backed	Demos, seed data, evaluation

Embedded mode (no daemon)

For scripts and notebooks, nexus.connect(config={"data_dir": ...}) runs an in-process instance with zero infrastructure. See Get started.

Docker image

Published to GHCR (multi-arch: amd64 + arm64):

ghcr.io/nexi-lab/nexus:stable          # latest release
ghcr.io/nexi-lab/nexus:edge            # latest develop
ghcr.io/nexi-lab/nexus:<version>       # pinned (e.g. 0.9.3)
ghcr.io/nexi-lab/nexus:stable-cuda     # GPU variant

Storage architecture

Four pillars, separated by access pattern — not by domain:

Pillar	Interface	Capability	Required?
Metastore	MetastoreABC	Ordered KV, CAS, prefix scan, optional Raft	Yes — sole kernel init param
ObjectStore	ObjectStoreABC	Streaming blob I/O, petabyte scale	Mounted dynamically
RecordStore	RecordStoreABC	Relational ACID, JOINs, vector search	Services only — optional
CacheStore	CacheStoreABC	Ephemeral KV, pub/sub, TTL	Optional (defaults to null)

The kernel starts with just a Metastore. Everything else is layered on without changing a line of kernel code.

Performance

Agent-level: context engineering

Nexus Dynamic Discovery vs loading all tools into the LLM context (POC on BFCL benchmark):

Metric	Static (all tools in context)	Nexus Dynamic Discovery
Irrelevance detection accuracy	40-80%	100%
Token consumption (65 tools)	~276K	~61K (78% reduction)
Hallucination on irrelevant tools	frequent	zero
ECCA-R (cost per reliable answer)	high	2x better

Dynamic Discovery only loads relevant tools on demand via score-based search, so the LLM sees a clean context instead of 65+ tool definitions. Details: nexus-benchmarks.

Kernel-level: steering overhead is negligible

Kernel syscall latency (pure Rust, PathLocal + redb, Apple M-series):

Syscall	Latency	What's included
sys_stat	~727 ns	redb lookup + permission lease check
sys_read 1 KB	~3.4 us	permission + CAS resolve + hook dispatch + I/O
sys_readdir 100 entries	~68 us	metastore + backend merge
sys_rename	~6.6 us	atomic metastore + backend

The full steering stack (permission check, CAS resolution, hook dispatch, metastore lookup) adds < 2 us to a read. An LLM call takes 100-1000 ms. The infrastructure is invisible at agent-interaction timescales.

Requirements

• Python 3.14+ for the SDK and CLI
• Rust toolchain only needed for building from source (the Docker image and nexusd-cluster binary ship pre-built)

Contributing

git clone https://github.com/nexi-lab/nexus.git && cd nexus
uv python install 3.14
uv sync --extra dev --extra test
uv run pre-commit install
uv run pytest tests/

For semantic search work: uv sync --extra semantic-search

Claude Code users: see CLAUDE.md (local-only, not committed) for the full contributor guide.

Troubleshooting

ModuleNotFoundError: No module named 'nexus'

Install from PyPI: pip install nexus-ai-fs. The package name on PyPI is nexus-ai-fs, not nexus.

License

Apache License 2.0 — see LICENSE for details.

Built by SudoWork.