{"id":34253558,"url":"https://github.com/tursodatabase/agentfs","last_synced_at":"2026-03-03T16:45:59.024Z","repository":{"id":320675010,"uuid":"1082722503","full_name":"tursodatabase/agentfs","owner":"tursodatabase","description":"The filesystem for agents.","archived":false,"fork":false,"pushed_at":"2026-02-18T09:00:42.000Z","size":3905,"stargazers_count":2259,"open_issues_count":61,"forks_count":130,"subscribers_count":11,"default_branch":"main","last_synced_at":"2026-02-18T13:44:34.381Z","etag":null,"topics":["agents","filesystem","sqlite","turso"],"latest_commit_sha":null,"homepage":"https://www.agentfs.ai","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tursodatabase.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"licenses/LICENSE-fuser.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-24T17:05:06.000Z","updated_at":"2026-02-18T11:26:22.000Z","dependencies_parsed_at":"2025-10-30T17:32:18.736Z","dependency_job_id":null,"html_url":"https://github.com/tursodatabase/agentfs","commit_stats":null,"previous_names":["penberg/agentbox","penberg/agent-datakit","penberg/agentos","penberg/agentfs","tursodatabase/agentfs"],"tags_count":69,"template":false,"template_full_name":null,"purl":"pkg:github/tursodatabase/agentfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tursodatabase%2Fagentfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tursodatabase%2Fagentfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tursodatabase%2Fagentfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tursodatabase%2Fagentfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tursodatabase","download_url":"https://codeload.github.com/tursodatabase/agentfs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tursodatabase%2Fagentfs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30052132,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T15:26:47.567Z","status":"ssl_error","status_checked_at":"2026-03-03T15:26:17.132Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","filesystem","sqlite","turso"],"created_at":"2025-12-16T11:04:24.995Z","updated_at":"2026-03-03T16:45:59.012Z","avatar_url":"https://github.com/tursodatabase.png","language":"Rust","readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eAgentFS\u003c/h1\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  The filesystem for agents.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca title=\"Build Status\" target=\"_blank\" href=\"https://github.com/tursodatabase/agentfs/actions/workflows/rust.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/tursodatabase/agentfs/rust.yml?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca title=\"Rust\" target=\"_blank\" href=\"https://crates.io/crates/agentfs-sdk\"\u003e\u003cimg alt=\"Crate\" src=\"https://img.shields.io/crates/v/agentfs-sdk\"\u003e\u003c/a\u003e\n  \u003ca title=\"JavaScript\" target=\"_blank\" href=\"https://www.npmjs.com/package/agentfs-sdk\"\u003e\u003cimg alt=\"NPM\" src=\"https://img.shields.io/npm/v/agentfs-sdk\"\u003e\u003c/a\u003e\n  \u003ca title=\"Python\" target=\"_blank\" href=\"https://pypi.org/project/agentfs-sdk/\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/agentfs-sdk\"\u003e\u003c/a\u003e\n  \u003ca title=\"MIT\" target=\"_blank\" href=\"https://github.com/tursodatabase/agentfs/blob/main/LICENSE.md\"\u003e\u003cimg src=\"http://img.shields.io/badge/license-MIT-orange.svg?style=flat-square\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca title=\"Users's Discord\" target=\"_blank\" href=\"https://tur.so/discord\"\u003e\u003cimg alt=\"Chat with other users of Turso (and Turso Cloud) on Discord\" src=\"https://img.shields.io/discord/933071162680958986?label=Discord\u0026logo=Discord\u0026style=social\u0026label=Users\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n\u003e **⚠️ Warning:** This software is in BETA. It may still contain bugs and unexpected behavior. Use caution with production data and ensure you have backups.\n\n## 🎯 What is AgentFS?\n\nAgentFS is a filesystem explicitly designed for AI agents. Just as traditional filesystems provide file and directory abstractions for applications, AgentFS provides the storage abstractions that AI agents need.\n\nThe AgentFS repository consists of the following:\n\n* **SDK** - [TypeScript](sdk/typescript), [Python](sdk/python), and [Rust](sdk/rust) libraries for programmatic filesystem access.\n* **[CLI](MANUAL.md)** - Command-line interface for managing agent filesystems:\n  - Mount AgentFS on host filesystem with FUSE on Linux and NFS on macOS.\n  - Access AgentFS files with a command line tool.\n* **[AgentFS Specification](SPEC.md)** - SQLite-based agent filesystem specification.\n\n## 💡 Why AgentFS?\n\nAgentFS provides the following benefits for agent state management:\n\n* **Auditability**: Every file operation, tool call, and state change is recorded in a SQLite database file. Query your agent's complete history with SQL to debug issues, analyze behavior, or meet compliance requirements.\n* **Reproducibility**: Snapshot an agent's state at any point with cp agent.db snapshot.db. Restore it later to reproduce exact execution states, test what-if scenarios, or roll back mistakes.\n* **Portability**: The entire agent runtime—files, state, history —is stored in a single SQLite file. Move it between machines, check it into version control, or deploy it to any system where Turso runs.\n\nRead more about the motivation for AgentFS in the announcement [blog post](https://turso.tech/blog/agentfs).\n\n## 🧑‍💻 Getting Started\n\n### Using the CLI\n\nInstall the AgentFS CLI:\n\n```bash\ncurl -fsSL https://agentfs.ai/install | bash\n```\n\nInitialize an agent filesystem:\n\n```bash\n$ agentfs init my-agent\nCreated agent filesystem: .agentfs/my-agent.db\nAgent ID: my-agent\n```\n\nInspect the agent filesystem:\n\n```bash\n$ agentfs fs ls my-agent\nUsing agent: my-agent\nf hello.txt\n\n$ agentfs fs cat my-agent hello.txt\nhello from agent\n```\n\nYou can also use a database path directly:\n\n```bash\n$ agentfs fs cat .agentfs/my-agent.db hello.txt\nhello from agent\n```\n\nView the agent's action timeline:\n\n```bash\n$ agentfs timeline my-agent\nID   TOOL                 STATUS       DURATION STARTED\n4    execute_code         pending            -- 2024-01-05 09:44:20\n3    api_call             error           300ms 2024-01-05 09:44:15\n2    read_file            success          50ms 2024-01-05 09:44:10\n1    web_search           success        1200ms 2024-01-05 09:43:45\n```\n\nYou can mount an agent filesystem using FUSE (Linux) or NFS (macOS):\n\n```bash\n$ agentfs mount my-agent ./mnt\n$ echo \"hello\" \u003e ./mnt/hello.txt\n$ cat ./mnt/hello.txt\nhello\n```\n\nYou can also run a program in an experimental sandbox with the agent filesystem mounted at `/agent`:\n\n```bash\n$ agentfs run /bin/bash\nWelcome to AgentFS!\n\n$ echo \"hello from agent\" \u003e /agent/hello.txt\n$ cat /agent/hello.txt\nhello from agent\n$ exit\n```\n\nRead the **[User Manual](MANUAL.md)** for complete documentation.\n\n### Using the SDK\n\nInstall the SDK in your project:\n\n```bash\nnpm install agentfs-sdk\n```\n\nUse it in your agent code:\n\n```typescript\nimport { AgentFS } from 'agentfs-sdk';\n\n// Persistent storage with identifier\nconst agent = await AgentFS.open({ id: 'my-agent' });\n// Creates: .agentfs/my-agent.db\n\n// Or use ephemeral in-memory database\nconst ephemeralAgent = await AgentFS.open();\n\n// Key-value operations\nawait agent.kv.set('user:preferences', { theme: 'dark' });\nconst prefs = await agent.kv.get('user:preferences');\n\n// Filesystem operations\nawait agent.fs.writeFile('/output/report.pdf', pdfBuffer);\nconst files = await agent.fs.readdir('/output');\n\n// Tool call tracking\nawait agent.tools.record(\n  'web_search',\n  Date.now() / 1000,\n  Date.now() / 1000 + 1.5,\n  { query: 'AI' },\n  { results: [...] }\n);\n```\n\n### Examples\n\nThis source repository also contains examples that demonstrate how to integrate AgentFS with some popular AI frameworks:\n\n- **[Mastra](examples/mastra/research-assistant)** - Research assistant using the Mastra AI framework\n- **[Claude Agent SDK](examples/claude-agent/research-assistant)** - Research assistant using Anthropic's Claude Agent SDK\n- **[OpenAI Agents](examples/openai-agents/research-assistant)** - Research assistant using OpenAI Agents SDK\n- **[Firecracker](examples/firecracker)** - Minimal Firecracker VM with AgentFS mounted via NFSv3\n- **[AI SDK + just-bash](examples/ai-sdk-just-bash)** - Interactive AI agent using Vercel AI SDK with just-bash for command execution\n- **[Cloudflare Workers](examples/cloudflare)** - AI agent using AI SDK + just-bash on Cloudflare Workers with Durable Objects storage\n\nSee the **[examples](examples)** directory for more details.\n\n## 🔧 How AgentFS Works?\n\n\u003cimg align=\"right\" width=\"40%\" src=\".github/assets/agentfs-arch.svg\"\u003e\n\nAgentFS is an agent filesystem accessible through an SDK that provides three essential interfaces for agent state management:\n\n* **Filesystem:** A POSIX-like filesystem for files and directories\n* **Key-Value:** A key-value store for agent state and context\n* **Toolcall:** A toolcall audit trail for debugging and analysis\n\nAt the heart of AgentFS is the [agent filesystem](SPEC.md), a complete SQLite-based storage system for agents implemented using [Turso](https://github.com/tursodatabase/turso). Everything an agent does—every file it creates, every piece of state it stores, every tool it invokes—lives in a single SQLite database file.\n\n## 🤔 FAQ\n\n### How is AgentFS different from _X_?\n\n[Bubblewrap](https://github.com/containers/bubblewrap) provides filesystem isolation using Linux namespaces and overlays. While you could achieve similar isolation with a `bwrap` call that mounts `/` read-only and uses `--tmp-overlay` on the working directory, the key difference is persistence and queryability: with AgentFS, the upper filesystem is stored in a single SQLite database file, which you can query, snapshot, and move to another machine. Read more about the motivation in the announcement [blog post](https://turso.tech/blog/agentfs).\n\n[Docker Sandbox](https://www.docker.com/blog/docker-sandboxes-a-new-approach-for-coding-agent-safety/) and AgentFS are complementary rather than competing. AgentFS answers \"what happened and what's the state?\" while Docker Sandboxes answer \"how do I run this safely?\" You could use both together: run an agent inside a Docker Sandbox for security, while using AgentFS inside that sandbox for structured state management and audit trails.\n\n[Git worktrees](https://git-scm.com/docs/git-worktree) let you check out multiple branches of a repository into separate directories, allowing agents to work on independent copies of the source code—similar to AgentFS. But AgentFS solves the problem at a lower level. With git worktrees, nothing prevents an agent from modifying files outside its worktree: another agent's worktree, system files, or anything else on the filesystem. The isolation is purely conventional, not enforced. AgentFS provides filesystem-level copy-on-write isolation that's system-wide and cannot be bypassed—letting you safely run untrusted agents. And because it operates below git, it also handles untracked files, making it useful beyond just version-controlled source code.\n\n### Why implement AgentFS at the filesystem layer instead of using containers or VMs?\n\nThe filesystem layer gives us capabilities that block devices can't. First, because everything is stored in structured SQLite tables, you can query the filesystem, which is essential for auditability and debugging agent behavior. Second, SQLite's write-ahead log enables snapshotting and time-travel forking by capturing every filesystem change. Third, we can provide an SDK that works in environments such as serverless or the browser, where there's no way to mount a block device at all. Note that this approach works fine with containers and VMs too—you can use AgentFS via remote filesystem protocols like NFS or through mechanisms like virtio-fuse.\n\n## 📚 Learn More\n\n- **[User Manual](MANUAL.md)** - Complete guide to using the AgentFS CLI and SDK\n- **[Agent Filesystem Specification](SPEC.md)** - Technical specification of the agent filesystem SQLite schema\n- **[SDK Examples](examples/)** - Working code examples using AgentFS\n- **[Turso database](https://github.com/tursodatabase/turso)** - an in-process SQL database, compatible with SQLite.\n\n### Blog Posts\n\n- **[Introducing AgentFS](https://turso.tech/blog/agentfs)** - The motivation behind AgentFS\n- **[AgentFS with FUSE](https://turso.tech/blog/agentfs-fuse)** - Mounting agent filesystems using FUSE\n- **[AgentFS with Overlay Filesystem](https://turso.tech/blog/agentfs-overlay)** - Sandboxing agents with copy-on-write overlays\n- **[AI Agents with Just Bash](https://turso.tech/blog/agentfs-just-bash)** - Safe bash command execution for agents\n- **[AgentFS in the Browser](https://turso.tech/blog/agentfs_browser)** - Running AgentFS in browsers with WebAssembly\n- **[Making Coding Agents Safe Using LlamaIndex](https://www.llamaindex.ai/blog/making-coding-agents-safe-using-llamaindex)** - Using AgentFS with LlamaIndex\n\n## 📝 License\n\nMIT\n","funding_links":[],"categories":["Personal Assistants \u0026 Conversational Agents","Rust","Foundational sandbox primitives and low-level tooling","AI Agents \u0026 Autonomy Frameworks"],"sub_categories":["Chatbots","Multiplatform"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftursodatabase%2Fagentfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftursodatabase%2Fagentfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftursodatabase%2Fagentfs/lists"}