AgentFS의 개요
AgentFS는 에이전트가 건드리는 모든 것을 이 회사의 SQLite 호환 엔진인 Turso 위에 만든 SQLite 데이터베이스 하나에 저장합니다. 그 파일 안에는 세 가지가 있습니다. inode와 디렉터리 항목 테이블로 저장되는 POSIX 방식의 파일 시스템, 상태를 담는 키-값 저장소, 그리고 도구 호출을 추가만 하는 로그입니다. 파일이 하나뿐이라 스냅샷은 데이터베이스를 그대로 복사하는 일이고, 에이전트의 이력은 로그에서 재구성하지 않고 SQL로 조회합니다.
프로젝트는 TypeScript, Python, Rust, Go용 SDK와 CLI를 제공합니다. CLI는 데이터베이스를 실제 파일 시스템으로 마운트하고(Linux는 FUSE, macOS는 NFS), `agentfs run`으로 쓰기 시 복사 샌드박스에서 프로그램을 실행하며, `agentfs timeline`으로 도구 호출 이력을 보여 주고, 파일과 키-값 저장소를 MCP나 NFS로 제공합니다. 선택 사항인 동기화는 데이터베이스를 Turso Cloud로 보냅니다. 대안은 로컬 저장 데이터 암호화이며, 둘은 함께 쓸 수 없습니다.
AgentFS, 쓸 만한 가치가 있습니까?
AgentFS의 쓸모는 파일 하나에 있습니다. 에이전트의 작업 파일, 키-값 상태, 호출한 모든 도구의 기록이 SQLite 데이터베이스 하나에 들어가므로, 잘못된 실행을 되돌리려면 이전 스냅샷을 다시 복사하면 되고, 무엇이 잘못됐는지 알아내는 일도 로그를 뒤지는 대신 SQL 쿼리 하나로 끝납니다. Turso의 Pekka Enberg와 Glauber Costa가 2025년 11월 13일에 발표했으며, 저장소의 GitHub 스타는 약 3,500개입니다.
CLI는 SDK만 보고 짐작하는 것보다 많은 일을 합니다. `agentfs run`은 프로젝트의 쓰기 시 복사 오버레이 위에서 셸이나 코딩 에이전트를 실행합니다. 쓰기는 데이터베이스로 가고 원본 파일은 그대로 남으며, Linux에서는 user namespaces를, macOS에서는 Apple의 샌드박스를 씁니다. `agentfs mount`는 데이터베이스를 일반 디렉터리로 보여 주므로 git과 grep 같은 도 구가 그대로 작동합니다. README는 git worktrees가 에이전트를 관례로만 분리하는 반면 오버레이는 에이전트 아래 계층에서 강제된다고 솔직하게 밝힙니다. npm 패키지는 2026년 11월 12일까지 일주일 동안 23,397회 다운로드되었습니다.
기본적으로 데이터는 로컬, 프로젝트 안의 .agentfs/<id>.db에 저장됩니다. `agentfs serve nfs`는 다른 주소에 바인딩하지 않는 한 127.0.0.1의 11111 포트에서 대기하며, 그 포트에 닿을 수 있는 사람은 누구나 파일을 마운트할 수 있습니다. 로컬 암호화는 직접 관리하는 16진수 키로 AES-256-GCM과 AEGIS 계열 암호를 지원합니다. Turso Cloud 동기화를 켜면 암호화는 쓸 수 없습니다.
주의할 점: 성숙도입니다. 2026년 2월 5일의 0.6.0 버전이 첫 베타였고, README는 여전히 백업 없이 운영 데이터를 맡기지 말라고 경고하며, 최신 릴리스인 v0.6.4는 3월 25일에 나왔습니다. 메인 브랜치의 마지막 커밋은 6월 3일의 lint 수정이었고, 트래커에는 열린 이슈 59건과 열린 풀 리퀘스트 18건이 있습니다. 스키마 변경에는 `agentfs migrate`가 필요하며, 더 엄격한 ptrace 기반 샌드박스는 실험 단계이고 Linux 전용입니다.
결론: 되돌리기와 감사 기록을 직접 만들지 않고 얻고 싶은 에이전트 인프라 개발자에게 AgentFS는 지금 가장 깔끔한 설계입니다. 노트북에서 돌리는 코딩 에이전트 하나라면 git과 컨테이너로 대부분 해결됩니다.
제 역할을 하는 곳
고객 저장소에서 코딩 에이전트를 돌리는 회사의 엔지니어
에이전 트가 파일을 자유롭게 바꾸게 하고 실행이 잘못되면 변경을 버리기
`agentfs run`으로 에이전트를 시작해 쓰기가 오버레이 데이터베이스에 쌓이게 하고, 끝나면 그 파일을 남기거나 버립니다. 소프트웨어는 무료이며, 비용은 베타의 위험과 자체 러너에 연결하는 시간입니다.
에이전트가 한 일을 감사인에게 보여 줘야 하는 플랫폼 팀
에이전트가 어떤 파일을 썼고 어떤 도구를 어떤 순서로 호출했는지 답하기
SDK로 도구 호출을 기록하고 추가 전용 로그와 파일 테이블을 SQL로 조회하거나 `agentfs timeline`을 읽습니다. 실행마다 데이터베이스 파일을 보관하면 증거가 한곳에 모입니다.
서버리스나 브라우저에서 에이전트를 만드는 개발자
디스크를 마운트할 수 없는 곳에서 에이전트에게 파일 시스템 제공하기
TypeScript SDK로 AgentFS 데이터베이스를 엽니다. 프로젝트는 Cloudflare Durable Objects와 WebAssembly에서의 예제도 보여 줍니다. 선택 사항인 Turso Cloud 동기화로 상태를 기기 간에 옮길 수 있습니다.
도입 전 확인할 점
- 설정
- 릴리스 페이지의 curl 설 치 프로그램으로 CLI를 설치한 뒤 `agentfs init my-agent`를 실행하면 .agentfs/my-agent.db가 생성됩니다. SDK는 `npm install agentfs-sdk`, pip, cargo로 설치합니다.
- 연동
- Mastra, Claude Agent SDK, OpenAI Agents SDK, just-bash를 쓴 Vercel AI SDK, Cloudflare Workers, Firecracker 예제가 있으며, MCP와 NFS 서버가 CLI에 내장되어 있습니다.
- 데이터와 개인정보
- Turso Cloud 동기화를 설정하지 않는 한 모든 것이 로컬 SQLite 파일에 남습니다. 로컬 저장 데이터 암호화는 사용자가 제공한 키를 쓰며, NFS 서버는 기본적으로 127.0.0.1에 바인딩되고 다른 주소에 바인딩하면 포트에 닿는 누구에게나 파일을 노출합니다.
- 대규모 사용 시 비용
- 소프트웨어는 무료입니다. Turso Cloud 동기화는 Turso의 별도 청구이며, 저장 공간은 데이터베이스에 남기는 파일 버전과 도구 호출만큼 늘어납니다.
- 제한
- 베타입니다. 스키마 업그레이드에는 `agentfs migrate`가 필요하고, Linux의 FUSE와 macOS의 NFS만 지원하며, ptrace 샌드박스는 실험 단계이자 Linux 전용이고, 암호화와 동기화는 동시에 쓸 수 없습니다.
좋은 점
- 파일, 키-값 상태, 도구 호출이 SQL로 조회할 수 있는 SQLite 파일 하나에 있음
- 스냅샷과 롤백이 파일 복사로 끝남
- 쓰기 시 복사 샌드박스가 Linux와 macOS에서 실제 프로젝트를 건드리지 않음
- TypeScript, Python, Rust, Go용 SDK와 MCP, NFS 서버 제공
아쉬운 점
- 베타 소프트웨어이며 README가 백업 없는 운영 데이터 사용을 경고함
- 2026년 3월 25일 v0.6.4 이후 릴리스 없음
- 저장 데이터 암호화와 Turso Cloud 동기화를 함께 쓸 수 없음
- 저장소 루트에 라이선스 파일이 없고 README와 패키지 메타데이터에만 라이선스가 표기됨
추천 대상
에이전트 플랫폼이나 샌드박스를 만들면서 실행마다 검사하고 복사할 수 있는 데이터베이스 하나로 저장하려는 팀.
AgentFS 대안
AgentFS: 자주 묻는 질문
- AgentFS, 쓸 만한 가치가 있습니까?
- AgentFS는 에이전트의 파일, 상태, 도구 이력을 조회하고 복사할 수 있는 SQLite 파일 하나로 만듭니다. 깔끔한 아이디어지만 아직 베타 표기이고 봄 이후로 활동이 줄었습니다. 평점은 5점 만점에 3.7점입니다.
- AgentFS의 가격은 얼마입니까?
- 무료 오픈 소스(README와 패키지 메타데이터 기준 MIT)입니다. 선택 사항인 동기화는 Turso Cloud로 가며, Turso가 별도로 청구합니다.
- AgentFS의 단점은 무엇입니까?
- 베타 소프트웨어이며 README가 백업 없는 운영 데이터 사용을 경고함; 2026년 3월 25일 v0.6.4 이후 릴리스 없음; 저장 데이터 암호화와 Turso Cloud 동기화를 함께 쓸 수 없음; 저장소 루트에 라이선스 파일이 없고 README와 패키지 메타데이터에만 라이선스가 표기됨.
- AgentFS에 적합한 사람은 누구입니까?
- 에이전트 플랫폼이나 샌드박스를 만들면서 실행마다 검사하고 복사할 수 있는 데이터베이스 하나로 저장하려는 팀.
- 팀이나 프로덕션 환경에서 AgentFS의 비용은 얼마입니까?
- 소프트웨어는 무료입니다. Turso Cloud 동기화는 Turso의 별도 청구이며, 저장 공간은 데이터베이스에 남기는 파일 버전과 도구 호출만큼 늘어납니다.
- AgentFS에 회사 데이터를 맡겨도 안전합니까?
- Turso Cloud 동기화를 설정하지 않는 한 모든 것이 로컬 SQLite 파일에 남습니다. 로컬 저장 데이터 암호화는 사용자가 제공한 키를 쓰며, NFS 서버는 기본적으로 127.0.0.1에 바인딩되고 다른 주소에 바인딩하면 포트에 닿는 누구에게나 파일을 노출합니다.
- AgentFS의 가장 좋은 대안은 무엇입니까?
- 저희가 리뷰한 것 중 가장 가까운 대안은 OpenSandbox, Anthropic Sandbox Runtime (srt) 및 Beads입니다.
답변 확인일: 2026년 11월 13일.