SurrealFS -- AI 에이전트용 가상 파일시스템
SurrealFS는 SurrealDB를 백엔드로 사용하는 영구적이고 쿼리 가능한 가상 파일시스템을 제공합니다. 세션 간 내구성 있는 파일 작업, 계층적 저장소, 콘텐츠 검색이 필요한 AI 에이전트를 위해 설계되었습니다.
구성 요소
| 구성 요소 | Crate/패키지 | 언어 | 목적 |
|---|---|---|---|
| 핵심 라이브러리 | surrealfs | Rust | 파일시스템 작업, CLI REPL, SurrealDB 저장소 계층 |
| AI 에이전트 | surrealfs-ai | Python (Pydantic AI) | 도구 통합 및 HTTP 호스팅을 통한 에이전트 인터페이스 |
Rust 코어 -- 명령어
surrealfs 크레이트는 POSIX 스타일 명령어가 포함된 REPL을 제공합니다:
| 명령어 | 설명 |
|---|---|
ls | 디렉터리 내용 나열 |
cat | 파일 내용 표시 |
tail | 파일의 마지막 줄 표시 |
nl | 파일 줄 번호 매기기 |
grep | 파일 내용 검색 |
touch | 빈 파일 생성 |
mkdir | 디렉터리 생성 |
write_file | 파일에 내용 쓰기 |
edit | 파일 내용 편집 |
cp | 파일 복사 |
cd | 디렉터리 변경 |
pwd | 현재 작업 디렉터리 출력 |
외부 명령어 파이핑 지원: curl https://example.com > /pages/example.html
저장소 백엔드:
- 임베디드 RocksDB (로컬)
- WebSocket을 통한 원격 SurrealDB
Python AI 에이전트
Pydantic AI 기반으로 파일시스템 명령어를 미러링하는 도구를 제공합니다.
from surrealfs_ai import build_chat_agent
# 에이전트 생성 (기본 LLM: Claude Haiku)
agent = build_chat_agent()
# HTTP로 노출
import uvicorn
app = agent.to_web()
uvicorn.run(app, host="127.0.0.1", port=7932)
특징:
- 기본 LLM: Claude Haiku
- Pydantic Logfire(OpenTelemetry)를 통한 텔레메트리 -- 보안 섹션에서 비활성화 방법 참조
- 모든 파일시스템 작업을 에이전트 도구로 사용 가능
- HTTP 호스팅 (기본 포트 7932, 127.0.0.1에 바인딩)
- 경로 정규화: 가상 FS 루트
/는 격리됨; 경로가 호스트 파일시스템으로 이스케이프 불가
빠른 시작
# Rust 코어 설치
cargo install surrealfs
# 임베디드 저장소로 REPL 시작
surrealfs
# 또는 원격 SurrealDB 인스턴스에 연결
surrealfs --endpoint ws://localhost:8000 --user root --pass root --ns agent --db workspace
# Python 에이전트 설치
pip install surrealfs-ai
# 에이전트 HTTP 서버 실행
python -m surrealfs_ai --host 127.0.0.1 --port 7932
사용 사례
- AI 에이전트 세션을 위한 영구 작업 공간
- 메타데이터 쿼리가 가능한 계층적 문서 저장소
- SurrealDB 권한을 통한 다중 에이전트 공유 파일 접근
- 콘텐츠 전략 및 지식 관리
- 프로젝트 스캐폴딩 및 템플릿 관리
보안 고려 사항
자격 증명: 원격 SurrealDB 연결에는 --user/--pass가 필요합니다.
특정 네임스페이스/데이터베이스로 범위가 지정된 전용 최소 권한 자격 증명을 사용하세요.
공유 또는 프로덕션 환경에서는 root 자격 증명을 절대 사용하지 마세요.
텔레메트리: Python 에이전트는 Pydantic Logfire(OpenTelemetry)를 사용합니다.
텔레메트리를 비활성화하려면 export LOGFIRE_SEND_TO_LOGFIRE=false를 설정하거나
코드에서 send_to_logfire=False로 Logfire를 구성하세요. 민감한 데이터가 있는 환경에서
활성화하기 전에 텔레메트리 엔드포인트를 감사하세요.
HTTP 바인딩: 에이전트는 기본적으로 127.0.0.1에 바인딩됩니다.
인증 및 TLS 없이 0.0.0.0이나 공용 네트워크에 노출하지 마세요.
컨테이너에서 실행하는 경우 네트워크 격리를 사용하세요.
파이프 명령어: Rust 코어는 콘텐츠 수집을 위해 curl URL > /path 구문을 지원합니다.
이는 호스트에서 파이프 소스 명령어를 실행합니다. 통제된 환경에서 신뢰할 수 있는 URL만 사용하세요.
신뢰할 수 없는 입력이 파이프 명령어를 구성하도록 허용하지 마세요.
샌드박싱: 가상 FS 루트(/)는 호스트 파일시스템이 아닌 SurrealDB 기반 추상화입니다.
경로 탐색(예: ../../etc/passwd)은 정규화되어 거부됩니다.
그러나 파이프 명령어는 호스트에서 실행되므로 -- 신뢰할 수 없는 에이전트 입력을 받는 경우
컨테이너나 샌드박스에서 실행하세요.
전체 문서
자세한 안내는 주요 스킬의 규칙 파일을 참조하세요:
- rules/surrealfs.md -- 아키텍처, Rust 코어 API, Python 에이전트 설정, SurrealDB 스키마, 다중 에이전트 패턴 및 배포
- surrealdb/surrealfs -- 상위 저장소