← Back to Skills Marketplace
surrealfs
by
Basit Mustafa
· GitHub ↗
· v1.2.1
· MIT-0
636
Downloads
2
Stars
0
Active Installs
4
Versions
Install in OpenClaw
/install surrealfs
Description
SurrealFS virtual filesystem for AI agents. Rust core + Python agent (Pydantic AI). Persistent file operations backed by SurrealDB. Part of the surreal-skill...
Usage Guidance
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.
Capability Analysis
Type: OpenClaw Skill
Name: surrealfs
Version: 1.2.1
The skill bundle includes a high-risk feature in the Rust core that allows executing host-level shell commands via piping (e.g., 'curl URL > /path'), which creates a direct vector for Remote Code Execution (RCE). While SKILL.md acknowledges this risk and provides security warnings, the inherent capability for an AI agent to trigger host-side execution is a significant vulnerability. Additionally, the agent utilizes external telemetry (Pydantic Logfire) and requires sensitive database credentials, expanding the potential impact of a compromise.
Capability Assessment
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.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install surrealfs - After installation, invoke the skill by name or use
/surrealfs - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.2.1
- No changes detected in this version.
- Version bump to 1.2.1 with no file or documentation updates.
v1.2.0
No user-facing changes in this release.
- Version bump to 1.2.0 with no code or documentation changes detected.
- All functionality and documentation remain unchanged from the previous version.
v1.1.1
Sync to v1.1.1: upstream SHA updates, security hardening.
v1.0.3
- Updated SKILL.md with detailed documentation on SurrealFS features, architecture, and usage.
- Added command reference for Rust core REPL and storage backend options.
- Included setup and integration steps for the Python AI agent.
- Documented key use cases and quick start instructions.
- Provided links to full documentation and upstream repository.
Metadata
Frequently Asked Questions
What is surrealfs?
SurrealFS virtual filesystem for AI agents. Rust core + Python agent (Pydantic AI). Persistent file operations backed by SurrealDB. Part of the surreal-skill... It is an AI Agent Skill for Claude Code / OpenClaw, with 636 downloads so far.
How do I install surrealfs?
Run "/install surrealfs" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is surrealfs free?
Yes, surrealfs is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does surrealfs support?
surrealfs is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created surrealfs?
It is built and maintained by Basit Mustafa (@24601); the current version is v1.2.1.
More Skills