{"id":32791314,"url":"https://github.com/penberg/agentfs","last_synced_at":"2025-11-05T13:01:22.826Z","repository":{"id":320675010,"uuid":"1082722503","full_name":"penberg/agentfs","owner":"penberg","description":"The filesystem for agents","archived":false,"fork":false,"pushed_at":"2025-11-04T08:18:33.000Z","size":98,"stargazers_count":8,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-04T09:10:53.034Z","etag":null,"topics":["agents","filesystem","operating-system"],"latest_commit_sha":null,"homepage":"","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/penberg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-11-04T08:27:00.000Z","dependencies_parsed_at":"2025-10-30T17:32:18.736Z","dependency_job_id":null,"html_url":"https://github.com/penberg/agentfs","commit_stats":null,"previous_names":["penberg/agentbox","penberg/agent-datakit","penberg/agentos","penberg/agentfs"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/penberg/agentfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penberg%2Fagentfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penberg%2Fagentfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penberg%2Fagentfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penberg%2Fagentfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/penberg","download_url":"https://codeload.github.com/penberg/agentfs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/penberg%2Fagentfs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282823603,"owners_count":26733133,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-05T02:00:05.946Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","operating-system"],"created_at":"2025-11-05T13:00:28.984Z","updated_at":"2025-11-05T13:01:22.824Z","avatar_url":"https://github.com/penberg.png","language":"Rust","funding_links":[],"categories":["Agent Integration \u0026 Deployment Tools"],"sub_categories":["AI Agent Development"],"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---\n\n\u003e **⚠️ Warning:** This software is ALPHA; use only for development, testing, and experimentation. We are working to make it production-ready, but do not use it for critical data until it is ready.\n\n## What is AgentFS?\n\nAgentFS is a filesystem designed specifically for AI agents. Just as traditional filesystems provide file and directory abstractions for applications, AgentFS provides the storage abstractions that AI agents need.\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). It combines three essential components: a POSIX-like virtual filesystem for files and directories, a key-value store for agent state and context, and an audit trail tool for debugging and analysis. 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## Components\n\nAgentFS provides four main components:\n\n* **[CLI](MANUAL.md)** - Command-line interface for managing agents\n* **SDK** - TypeScript and Rust libraries for programmatic access\n* **Sandbox** - Linux-compatible execution environment\n* **[Specification](SPEC.md)** - SQLite-based filesystem architecture\n\n## Getting Started\n\n### Using the CLI\n\nInitialize an agent filesystem:\n\n```bash\n$ agentfs init\nCreated agent filesystem: agent.db\n```\n\nRun a program in the 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\nInspect the agent filesystem from outside:\n\n```bash\n$ agentfs fs ls\nf hello.txt\n\n$ agentfs fs cat hello.txt\nhello from agent\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\nconst agent = new AgentFS('./agent.db');\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\nSee the **[SDK documentation in MANUAL.md](MANUAL.md#agentfs-sdk)** and **[examples](sdk/examples/)** for more details.\n\n## Why AgentFS?\n\n**Auditability**: Every file operation, tool call, and state change is recorded in SQLite. Query your agent's complete history with SQL to debug issues, analyze behavior, or meet compliance requirements.\n\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\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\n**Simplicity**: No configuration files, no database servers, no distributed systems. Just a single file and a simple API.\n\n**Sandboxing**: Run agents in an isolated Linux environment where filesystem access is controlled and monitored. Perfect for testing untrusted code or enforcing security policies.\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 SQLite schema\n- **[SDK Examples](sdk/examples/)** - Working code examples\n- **[Turso database](https://github.com/tursodatabase/turso)** - an in-process SQL database, compatible with SQLite.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpenberg%2Fagentfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpenberg%2Fagentfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpenberg%2Fagentfs/lists"}