SurrealFS -- Sistema de Archivos Virtual para Agentes de IA
SurrealFS proporciona un sistema de archivos virtual persistente y consultable respaldado por SurrealDB. Diseñado para agentes de IA que necesitan operaciones de archivo duraderas, almacenamiento jerárquico y búsqueda de contenido entre sesiones.
Componentes
| Componente | Crate/Paquete | Lenguaje | Propósito |
|---|---|---|---|
| Biblioteca Principal | surrealfs | Rust | Operaciones del sistema de archivos, REPL CLI, capa de almacenamiento SurrealDB |
| Agente de IA | surrealfs-ai | Python (Pydantic AI) | Interfaz de agente con integración de herramientas, alojamiento HTTP |
Núcleo Rust -- Comandos
El crate surrealfs proporciona un REPL con comandos similares a POSIX:
| Comando | Descripción |
|---|---|
ls | Listar contenido del directorio |
cat | Mostrar contenido del archivo |
tail | Mostrar últimas líneas de un archivo |
nl | Numerar líneas de un archivo |
grep | Buscar en contenido de archivos |
touch | Crear archivo vacío |
mkdir | Crear directorio |
write_file | Escribir contenido en un archivo |
edit | Editar contenido de un archivo |
cp | Copiar archivo |
cd | Cambiar directorio |
pwd | Mostrar directorio de trabajo |
Soporta redirección desde comandos externos: curl https://example.com > /pages/example.html\n
Backends de almacenamiento:
- RocksDB embebido (local)
- SurrealDB remoto vía WebSocket
Agente Python de IA
Construido sobre Pydantic AI con herramientas que reflejan los comandos del sistema de archivos.
from surrealfs_ai import build_chat_agent
# Crear el agente (LLM por defecto: Claude Haiku)
agent = build_chat_agent()
# Exponer sobre HTTP
import uvicorn
app = agent.to_web()
uvicorn.run(app, host="127.0.0.1", port=7932)
Características:
- LLM por defecto: Claude Haiku
- Telemetría vía Pydantic Logfire (OpenTelemetry) -- ver sección de Seguridad para desactivación
- Todas las operaciones del sistema de archivos disponibles como herramientas del agente
- Alojamiento HTTP (puerto por defecto 7932, vinculado a 127.0.0.1)
- Normalización de rutas: la raíz del FS virtual
/está aislada; las rutas no pueden escapar al sistema de archivos anfitrión
Inicio Rápido
# Instalar el núcleo Rust
cargo install surrealfs
# Iniciar el REPL con almacenamiento embebido
surrealfs
# O conectar a una instancia remota de SurrealDB
surrealfs --endpoint ws://localhost:8000 --user root --pass root --ns agent --db workspace
# Instalar el agente Python
pip install surrealfs-ai
# Ejecutar el servidor HTTP del agente
python -m surrealfs_ai --host 127.0.0.1 --port 7932
Casos de Uso
- Espacio de trabajo persistente para sesiones de agentes de IA
- Almacenamiento jerárquico de documentos con consultas de metadatos
- Acceso compartido a archivos entre múltiples agentes con permisos de SurrealDB
- Gestión de estrategia de contenido y conocimiento
- Creación de plantillas y andamiaje de proyectos
Consideraciones de Seguridad
Credenciales: Las conexiones remotas a SurrealDB requieren --user/--pass. Use
credenciales dedicadas de mínimo privilegio y limitadas a un namespace/base de datos específico.
Nunca use credenciales root en entornos compartidos o de producción.
Telemetría: El agente Python usa Pydantic Logfire (OpenTelemetry). Para
deshabilitar la telemetría, configure: export LOGFIRE_SEND_TO_LOGFIRE=false o configure
Logfire con send_to_logfire=False en código. Audite los endpoints de telemetría antes de
habilitarlos en entornos con datos sensibles.
Vinculación HTTP: El agente se vincula a 127.0.0.1 por defecto. No lo exponga a
0.0.0.0 o redes públicas sin autenticación y TLS. Si se ejecuta en un
contenedor, use aislamiento de red.
Comandos Pipe: El núcleo Rust soporta la sintaxis curl URL > /path para la entrada
de contenido. Esto ejecuta el comando fuente del pipe en el anfitrión. Use solo con
URLs de confianza en entornos controlados. No permita que entradas no confiables
construyan comandos pipe.
Aislamiento: La raíz del FS virtual (/) es una abstracción respaldada por SurrealDB,
no el sistema de archivos anfitrión. La navegación de rutas (p.ej., ../../etc/passwd) se
normaliza y rechaza. Sin embargo, los comandos pipe se ejecutan en el anfitrión -- ejecute
en un contenedor o entorno aislado si acepta entradas de agente no confiables.
Documentación Completa
Consulte el archivo de reglas principal para obtener orientación completa:
- rules/surrealfs.md -- arquitectura, API del núcleo Rust, configuración del agente Python, esquema SurrealDB, patrones de múltiples agentes y despliegue
- surrealdb/surrealfs -- repositorio upstream