# Surrealfs

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

- **Type:** Skill
- **Install:** `agentstack add skill-24601-surreal-skills-surrealfs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [24601](https://agentstack.voostack.com/s/24601)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [24601](https://github.com/24601)
- **Source:** https://github.com/24601/surreal-skills/tree/main/skills/surrealfs
- **Website:** https://surrealdb.com

## Install

```sh
agentstack add skill-24601-surreal-skills-surrealfs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

```python
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

```bash
# 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](../../rules/surrealfs.md)** -- architecture, Rust core API, Python agent setup, SurrealDB schema, multi-agent patterns, and deployment
- **[surrealdb/surrealfs](https://github.com/surrealdb/surrealfs)** -- upstream repository

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [24601](https://github.com/24601)
- **Source:** [24601/surreal-skills](https://github.com/24601/surreal-skills)
- **License:** MIT
- **Homepage:** https://surrealdb.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-24601-surreal-skills-surrealfs
- Seller: https://agentstack.voostack.com/s/24601
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.