surrealfs

SurrealFS virtual filesystem for AI agents. Rust core + Python agent (Pydantic AI). Persistent file operations backed by SurrealDB. Part of the surreal-skill...

Security Scan

The skill's README-style instructions match a plausible SurrealFS purpose, but the registry metadata omits required credentials and install steps and the runtime instructions permit host command execution and telemetry; those mismatches and exposures warrant caution.

Purpose & Capability

The SKILL.md clearly requires SurrealDB credentials (SURREAL_ENDPOINT, SURREAL_USER, SURREAL_PASS) and documents installing Rust and Python packages, but the registry metadata claims no required env vars and no required binaries. That metadata/instruction mismatch is incoherent — the skill legitimately needs DB credentials and toolchains for its stated purpose, so the registry entry is incomplete or inaccurate.

Instruction Scope

Runtime instructions instruct running 'cargo install', 'pip install', starting a local HTTP agent, and using the Rust REPL which supports piping like 'curl URL > /path' (the SKILL.md explicitly says pipe sources execute on the host). Those instructions expand scope beyond a pure in-process helper: they can install packages, host an HTTP service, and execute host commands via pipes. The doc warns about these risks but still permits behaviors that can run arbitrary host commands if the agent constructs pipe commands.

Install Mechanism

There is no formal install spec in the registry, but SKILL.md tells users to run 'cargo install surrealfs' and 'pip install surrealfs-ai'. Those are standard package managers (crates.io / PyPI) — moderate risk and expected for this project — but the registry should have reflected that. The lack of an explicit, verifiable install spec or upstream checksum reduces transparency.

Credentials

SKILL.md documents SURREAL_ENDPOINT, SURREAL_USER, SURREAL_PASS and a telemetry opt-out env (LOGFIRE_SEND_TO_LOGFIRE), none of which appear in the registry's required env list. The skill also names a default LLM (Claude Haiku) which implies external model credentials or endpoints that are not declared. Required secrets and telemetry endpoints are not proportionately represented in the metadata.

Persistence & Privilege

The skill is not force-installed (always: false) and allows normal autonomous invocation. It runs a local HTTP server (127.0.0.1:7932 by default) and the Rust core can execute host pipe commands; this increases the blast radius if the agent is given untrusted inputs. This is a significant operational consideration, but not an automatic privilege escalation in the registry itself.

What to consider before installing

Do not install blindly. Key points to check before proceeding: - Metadata mismatch: the registry claims no required env vars or binaries but SKILL.md requires SurrealDB creds and recommends cargo/pip installs. Confirm the registry is updated or that you trust the upstream source. - Network & telemetry: the agent may send telemetry (Logfire/OpenTelemetry) unless you opt out; audit destinations and set LOGFIRE_SEND_TO_LOGFIRE=false if you do not want telemetry. - Host command execution: the Rust REPL supports piping (e.g., 'curl URL > /path') which runs host commands. Run the skill only in a sandbox/container and never expose the agent to untrusted inputs or to 0.0.0.0 without auth/TLS. - Least privilege: create and use least-privilege SurrealDB credentials scoped to a single namespace/db; never use root for shared/production usage. - Verify upstream: the SKILL.md points to an upstream GitHub repo; inspect that repository, its releases, and checksums before running cargo/pip installs. If the owner/slug is unfamiliar, request provenance or an install spec with fixed package versions. If the registry metadata is corrected (declares the env vars and install steps) and you verify the upstream package/repo, the skill would look coherent for its purpose; until then treat it as suspicious.

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

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:

• rules/surrealfs.md -- architecture, Rust core API, Python agent setup, SurrealDB schema, multi-agent patterns, and deployment
• surrealdb/surrealfs -- upstream repository