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 | INLINECODE0 | 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 |
|---|
| INLINECODE3 | List directory contents |
| INLINECODE4 |
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: INLINECODE15
Storage backends:
- - Embedded RocksDB (local)
- Remote SurrealDB via WebSocket
Python AI Agent
Built on Pydantic AI with tools that mirror the filesystem commands.
CODEBLOCK0
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
CODEBLOCK1
Use Cases
- - Persistent workspace for AI agent sessions
- Hierarchical document storage with metadata queries
- Multi-agent shared file access with SurrealDB permissions
- Content strategy and knowledge management
- Project scaffolding and template management
Security Considerations
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.
Full Documentation
See the main skill's rule file for complete guidance:
SurrealFS —— 面向AI代理的虚拟文件系统
SurrealFS 提供了一个由 SurrealDB 支持的持久化、可查询的虚拟文件系统。
专为需要跨会话持久化文件操作、分层存储和内容搜索的 AI 代理设计。
组件
| 组件 | 包/库 | 语言 | 用途 |
|---|
| 核心库 | surrealfs | Rust | 文件系统操作、CLI REPL、SurrealDB 存储层 |
| AI 代理 |
surrealfs-ai | Python (Pydantic AI) | 集成工具的代理接口、HTTP 托管 |
Rust 核心 —— 命令
surrealfs 库提供了一个带有类 POSIX 命令的 REPL：
显示文件内容 |
| tail | 显示文件末尾几行 |
| nl | 为文件行编号 |
| grep | 搜索文件内容 |
| touch | 创建空文件 |
| mkdir | 创建目录 |
| write_file | 向文件写入内容 |
| edit | 编辑文件内容 |
| cp | 复制文件 |
| cd | 切换目录 |
| pwd | 打印当前工作目录 |
支持从外部命令管道输入：curl https://example.com > /pages/example.html
存储后端：
- - 嵌入式 RocksDB（本地）
- 通过 WebSocket 连接的远程 SurrealDB
Python AI 代理
基于 Pydantic AI 构建，提供镜像文件系统命令的工具。
python
from surrealfsai import buildchat_agent
创建代理（默认 LLM：Claude Haiku）
agent = build
chatagent()
通过 HTTP 暴露
import uvicorn
app = agent.to_web()
uvicorn.run(app, host=127.0.0.1, port=7932)
特性：
- - 默认 LLM：Claude Haiku
- 通过 Pydantic Logfire（OpenTelemetry）进行遥测 —— 参见安全部分了解如何退出
- 所有文件系统操作均可作为代理工具使用
- HTTP 托管（默认端口 7932，绑定到 127.0.0.1）
- 路径规范化：虚拟 FS 根目录 / 是隔离的；路径无法逃逸到主机文件系统
快速开始
bash
安装 Rust 核心
cargo install surrealfs
使用嵌入式存储启动 REPL
surrealfs
或连接到远程 SurrealDB 实例
surrealfs --endpoint ws://localhost:8000 --user root --pass root --ns agent --db workspace
安装 Python 代理
pip install surrealfs-ai
运行代理 HTTP 服务器
python -m surrealfs_ai --host 127.0.0.1 --port 7932
使用场景
- - AI 代理会话的持久化工作空间
- 支持元数据查询的分层文档存储
- 基于 SurrealDB 权限的多代理共享文件访问
- 内容策略和知识管理
- 项目脚手架和模板管理
安全考虑
凭据：远程 SurrealDB 连接需要 --user/--pass。使用限定于特定命名空间/数据库的专用、最小权限凭据。切勿在共享或生产环境中使用 root 凭据。
遥测：Python 代理使用 Pydantic Logfire（OpenTelemetry）。要禁用遥测，请设置：export LOGFIRESENDTOLOGFIRE=false 或在代码中使用 sendto_logfire=False 配置 Logfire。在包含敏感数据的环境中启用前，请审核遥测端点。
HTTP 绑定：代理默认绑定到 127.0.0.1。未经身份验证和 TLS 加密，请勿暴露到 0.0.0.0 或公共网络。如果在容器中运行，请使用网络隔离。
管道命令：Rust 核心支持 curl URL > /path 语法用于内容导入。这会在主机上执行管道源命令。仅在受控环境中使用受信任的 URL。不允许不受信任的输入构造管道命令。
沙箱：虚拟 FS 根目录（/）是一个由 SurrealDB 支持的抽象，而非主机文件系统。路径遍历（例如 ../../etc/passwd）会被规范化并拒绝。然而，管道命令在主机上执行 —— 如果接受不受信任的代理输入，请在容器或沙箱中运行。
完整文档
有关完整指南，请参阅主要技能的规则文件：
