SurrealFS virtual filesystem for AI agents. Rust core + Python agent (Pydantic AI). Persistent file operations backed by SurrealDB. Part of the surreal-skills collection.
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.
| 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 |
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:
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:
/ is isolated; paths cannot escape to host filesystem# 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
Credentials: Remote SurrealDB connections require --user/--pass. Use
dedicated, least-privilege credentials scoped to a specific namespace/database.
Never use root credentials in shared or production environments.
Telemetry: The Python agent uses Pydantic Logfire (OpenTelemetry). To
disable telemetry, set: export LOGFIRE_SEND_TO_LOGFIRE=false or configure
Logfire with send_to_logfire=False in code. Audit telemetry endpoints before
enabling in environments with sensitive data.
HTTP binding: The agent binds to 127.0.0.1 by default. Do not expose to
0.0.0.0 or public networks without authentication and TLS. If running in a
container, use network isolation.
Pipe commands: The Rust core supports curl URL > /path syntax for content
ingress. This executes the pipe source command on the host. Use only with
trusted URLs in controlled environments. Do not allow untrusted input to
construct pipe commands.
Sandboxing: The virtual FS root (/) is a SurrealDB-backed abstraction,
not the host filesystem. Path traversal (e.g., ../../etc/passwd) is
normalized and rejected. However, pipe commands execute on the host -- run
in a container or sandbox if accepting untrusted agent input.
See the main skill's rule file for complete guidance: