SurrealFS — Sistema de Arquivos Virtual para Agentes de IA
O SurrealFS fornece um sistema de arquivos virtual persistente e consultável apoiado pelo SurrealDB. Projetado para agentes de IA que precisam de operações duráveis de arquivos, armazenamento hierárquico e busca de conteúdo entre sessões.
Componentes
| Componente | Crate/Pacote | Linguagem | Propósito |
|---|---|---|---|
| Biblioteca Principal | surrealfs | Rust | Operações do sistema de arquivos, REPL CLI, camada de armazenamento SurrealDB |
| Agente de IA | surrealfs-ai | Python (Pydantic AI) | Interface do agente com integração de ferramentas, hospedagem HTTP |
Núcleo Rust — Comandos
A crate surrealfs fornece um REPL com comandos similares ao POSIX:
| Comando | Descrição |
|---|---|
ls | Listar conteúdo do diretório |
cat | Exibir conteúdo do arquivo |
tail | Mostrar últimas linhas de um arquivo |
nl | Numerar linhas de um arquivo |
grep | Pesquisar conteúdo do arquivo |
touch | Criar arquivo vazio |
mkdir | Criar diretório |
write_file | Escrever conteúdo em arquivo |
edit | Editar conteúdo do arquivo |
cp | Copiar arquivo |
cd | Mudar diretório |
pwd | Exibir diretório de trabalho |
Suporta redirecionamento de comandos externos: curl https://example.com > /pages/example.html
Backends de armazenamento:
- RocksDB embutido (local)
- SurrealDB remoto via WebSocket
Agente Python
Construído sobre Pydantic AI com ferramentas que espelham os comandos do sistema de arquivos.
from surrealfs_ai import build_chat_agent
# Cria o agente (LLM padrão: Claude Haiku)
agent = build_chat_agent()
# Expõe via HTTP
import uvicorn
app = agent.to_web()
uvicorn.run(app, host="127.0.0.1", port=7932)
Funcionalidades:
- LLM padrão: Claude Haiku
- Telemetria via Pydantic Logfire (OpenTelemetry) — consulte a seção de Segurança para desabilitar
- Todas as operações do sistema de arquivos disponíveis como ferramentas do agente
- Hospedagem HTTP (porta padrão 7932, vinculada a 127.0.0.1)
- Normalização de caminhos: a raiz virtual do FS
/é isolada; caminhos não podem escapar para o sistema de arquivos do host
Guia Rápido
# Instalar o núcleo Rust
cargo install surrealfs
# Iniciar o REPL com armazenamento embutido
surrealfs
# Ou conectar a uma instância remota de SurrealDB
surrealfs --endpoint ws://localhost:8000 --user root --pass root --ns agent --db workspace
# Instalar o agente Python
pip install surrealfs-ai
# Executar o servidor HTTP do agente
python -m surrealfs_ai --host 127.0.0.1 --port 7932
Casos de Uso
- Espaço de trabalho persistente para sessões de agentes de IA
- Armazenamento hierárquico de documentos com consultas de metadados
- Acesso compartilhado a arquivos entre múltiplos agentes com permissões SurrealDB
- Estratégia de conteúdo e gerenciamento de conhecimento
- Scaffolding de projetos e gerenciamento de templates
Considerações de Segurança
Credenciais: Conexões remotas com SurrealDB exigem --user/--pass. Use
credenciais dedicadas com privilégios mínimos, restritas a um namespace/banco de dados específico.
Nunca use credenciais root em ambientes compartilhados ou de produção.
Telemetria: O agente Python usa Pydantic Logfire (OpenTelemetry). Para
desabilitar a telemetria, defina: export LOGFIRE_SEND_TO_LOGFIRE=false ou configure
o Logfire com send_to_logfire=False no código. Audite os endpoints de telemetria antes de
ativá-la em ambientes com dados sensíveis.
Vínculo HTTP: O agente vincula-se a 127.0.0.1 por padrão. Não exponha a
0.0.0.0 ou redes públicas sem autenticação e TLS. Se executado em um
contêiner, use isolamento de rede.
Comandos pipe: O núcleo Rust suporta a sintaxe curl URL > /path para entrada
de conteúdo. Isso executa o comando de origem do pipe no host. Use apenas com
URLs confiáveis em ambientes controlados. Não permita que entradas não confiáveis construam
comandos pipe.
Sandboxing: A raiz virtual do FS (/) é uma abstração apoiada pelo SurrealDB,
não o sistema de arquivos do host. A travessia de caminhos (por exemplo, ../../etc/passwd) é
normalizada e rejeitada. No entanto, comandos pipe são executados no host — execute
em um contêiner ou sandbox se estiver aceitando entrada não confiável de um agente.
Documentação Completa
Consulte o arquivo de regras principal da skill para orientação completa:
- rules/surrealfs.md — arquitetura, API do núcleo Rust, configuração do agente Python, esquema SurrealDB, padrões multi-agentes e implantação
- surrealdb/surrealfs — repositório upstream