surrealfs

SurrealFS -- Virtual Filesystem for AI Agents

SurrealFS provides a persistent, queryable virtual filesystem backed by SurrealDB. Designed for AI agents that need durable file operations, hierarchical storage, and content search across sessions.

Components

Component	Crate/Package	Language	Purpose
Core Library	surrealfs	Rust	Filesystem operations, CLI REPL, SurrealDB storage layer
AI Agent	surrealfs-ai	Python (Pydantic AI)	Agent interface with tool integration, HTTP hosting

Rust Core -- Commands

The surrealfs crate provides a REPL with POSIX-like commands:

Command	Description
ls	List directory contents
cat	Display file contents
tail	Show last lines of a file
nl	Number lines of a file
grep	Search file contents
touch	Create empty file
mkdir	Create directory
write_file	Write content to file
edit	Edit file contents
cp	Copy file
cd	Change directory
pwd	Print working directory

Supports piping from external commands: curl https://example.com > /pages/example.html

Storage backends:

• Embedded RocksDB (local)
• Remote SurrealDB via WebSocket

Python AI Agent

Built on Pydantic AI with tools that mirror the filesystem commands.

from surrealfs_ai import build_chat_agent

# Create the agent (default LLM: Claude Haiku)
agent = build_chat_agent()

# Expose over HTTP
import uvicorn
app = agent.to_web()
uvicorn.run(app, host="127.0.0.1", port=7932)

Features:

• Default LLM: Claude Haiku
• Telemetry via Pydantic Logfire (OpenTelemetry) -- see Security section for opt-out
• All filesystem operations available as agent tools
• HTTP hosting (default port 7932, bound to 127.0.0.1)
• Path normalization: virtual FS root / is isolated; paths cannot escape to host filesystem

Quick Start

# Install the Rust core
cargo install surrealfs

# Start the REPL with embedded storage
surrealfs

# Or connect to a remote SurrealDB instance
surrealfs --endpoint ws://localhost:8000 --user root --pass root --ns agent --db workspace

# Install the Python agent
pip install surrealfs-ai

# Run the agent HTTP server
python -m surrealfs_ai --host 127.0.0.1 --port 7932