If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/tursodatabase/agentfs shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Missing license — unclear to depend on

• Last commit 6w ago
• 6 active contributors
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 69% of recent commits
• ⚠ No license — legally unclear to depend on

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live tursodatabase/agentfs repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/tursodatabase/agentfs.

What it runs against: a local clone of tursodatabase/agentfs — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in tursodatabase/agentfs | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 74 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of tursodatabase/agentfs. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/tursodatabase/agentfs.git
#   cd agentfs
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of tursodatabase/agentfs and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "tursodatabase/agentfs(\\.git)?\\b" \\
  && ok "origin remote is tursodatabase/agentfs" \\
  || miss "origin remote is not tursodatabase/agentfs (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cli/src/main.rs" \\
  && ok "cli/src/main.rs" \\
  || miss "missing critical file: cli/src/main.rs"
test -f "cli/src/cmd/mod.rs" \\
  && ok "cli/src/cmd/mod.rs" \\
  || miss "missing critical file: cli/src/cmd/mod.rs"
test -f "cli/src/mount/mod.rs" \\
  && ok "cli/src/mount/mod.rs" \\
  || miss "missing critical file: cli/src/mount/mod.rs"
test -f "cli/src/fuse.rs" \\
  && ok "cli/src/fuse.rs" \\
  || miss "missing critical file: cli/src/fuse.rs"
test -f "cli/src/nfsserve/mod.rs" \\
  && ok "cli/src/nfsserve/mod.rs" \\
  || miss "missing critical file: cli/src/nfsserve/mod.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 74 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~44d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/tursodatabase/agentfs"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

AgentFS is a specialized filesystem designed for AI agents, enabling them to store and manage data more efficiently. It integrates SQLite for auditing file operations and supports FUSE on Linux and NFS on macOS for mounting agent filesystems. The core technology is based on Rust, with SDKs available in TypeScript and Python for programmatic access. This repository uses a monorepo structure where the core filesystem functionality is located in cli/src, with various command modules for different operations. The SDKs for TypeScript and Python are housed in sdk/typescript and sdk/python respectively, ensuring easy access to functionalities tailored for language-specific usage.

This project is intended for developers working on AI systems who require robust state management and reproducibility for agent workflows. Contributors could range from Rust developers implementing filesystems to data scientists automating AI agent interactions.

AgentFS is relatively mature but in BETA, with the repository currently having around 200 stars and multiple active contributors. The presence of CI workflows (like rust.yml and python.yml in .github/workflows) indicates ongoing testing and quality assurance. The last commit was recent, suggesting active development.

The project has a moderate dependency count, including essential libraries like tokio and serde, which are well-maintained. However, the BETA status introduces risks of bugs and breaking changes, and the project may still evolve significantly. The issue backlog seems manageable, but new contributors should find where issues arise to assess risk effectively.

Recent activity focuses on improving CLI command functionalities and expanding SDK capabilities for various languages. Specific PRs include enhancements to performance scripts and updates to documentation.

To get started, run the following commands in your terminal: git clone https://github.com/tursodatabase/agentfs.git and then cd agentfs && cargo build && cargo run.

Daily commands: You can start the CLI server by executing cargo run --bin agentfs in the project directory.

• cli/src/main.rs — Entry point for the agentfs CLI; orchestrates all command routing and initialization logic.
• cli/src/cmd/mod.rs — Command module dispatcher; defines all CLI subcommands (mount, run, exec, sync, etc.) that agents interact with.
• cli/src/mount/mod.rs — Mount orchestration layer; routes between FUSE and NFS filesystem implementations based on platform.
• cli/src/fuse.rs — FUSE filesystem implementation; core request-response loop handling file operations from agents.
• cli/src/nfsserve/mod.rs — NFS server implementation; alternative filesystem backend for network-based agent access.
• cli/src/sandbox/mod.rs — Sandboxing abstraction layer; enforces security policies via ptrace on Linux and native APIs on Darwin/Windows.
• cli/Cargo.toml — Rust dependency manifest; declares agentfs-sdk, tokio, reverie, and other critical runtime dependencies.

Add a new CLI command

1. Create a new command module in cli/src/cmd/ (e.g., cli/src/cmd/mycommand.rs) with a public async fn execute() function. (cli/src/cmd/mycommand.rs)
2. Declare the module in cli/src/cmd/mod.rs and add the subcommand variant to the Commands enum (derived from clap::Subcommand). (cli/src/cmd/mod.rs)
3. Add a pattern-match case in cmd::execute() to call your new command handler. (cli/src/cmd/mod.rs)
4. Define CLI args using clap derive macros in your command struct. (cli/src/cmd/mycommand.rs)

Add a new NFS RPC handler

1. Define the RPC procedure number and argument/reply structures (following NFSv3 spec) in a new module under cli/src/nfsserve/. (cli/src/nfsserve/nfs_handlers.rs)
2. Implement the handler function that decodes XDR args, calls vfs methods, and encodes XDR reply. (cli/src/nfsserve/nfs_handlers.rs)
3. Register the procedure in the NFS dispatch table in cli/src/nfsserve/rpc.rs to route incoming RPC calls. (cli/src/nfsserve/rpc.rs)
4. Implement corresponding VFS methods in cli/src/nfsserve/vfs.rs that backend the operation (e.g., read_file, write_file). (cli/src/nfsserve/vfs.rs)

Add a new sandboxing policy

1. Define the policy rule in cli/src/sandbox/mod.rs as a new enum variant or permission check. (cli/src/sandbox/mod.rs)
2. Implement the enforcement logic in cli/src/sandbox/linux_ptrace.rs for Linux (syscall interception) and cli/src/sandbox/darwin.rs for macOS. (cli/src/sandbox/linux_ptrace.rs)
3. Add integration tests in cli/tests/ that verify the policy blocks or allows expected syscalls. (cli/tests/all.sh)

Extend filesystem operation support

1. Identify the operation (e.g., new file attribute, new inode operation) and add it to the agentfs-sdk protocol. (cli/src/fuse.rs)
2. Implement the Filesystem trait method in cli/src/fuse.rs to handle requests from the kernel. (cli/src/fuse.rs)
3. Add corresponding NFS RPC procedure in cli/src/nfsserve/nfs_handlers.rs and VFS method in cli/src/nfsserve/vfs.rs if NFS support is needed. (cli/src/nfsserve/nfs_handlers.rs)

• FUSE (Linux/macOS) — Kernel-level filesystem interception without modifying agent code; used as primary mount backend on Unix-like systems.
• NFS v3 — Network filesystem protocol providing cross-platform agent access (including Windows/remote machines) with standard RPC.
• ptrace (Linux) + reverie — Syscall interception framework for enforcing sandboxing policies; reverie abstracts ptrace complexity.
• tokio (async Rust) — Concurrent handling of multiple mount requests, NFS RPC calls, and daemon lifecycle in a single thread pool.
• Turso SQL client — Potential backend for persisting filesystem metadata, audit logs, or policy rules (suggested by dependency).

• Separate FUSE and NFS implementations instead of unified abstraction

  • Why: Different protocol requirements and performance characteristics; FUSE is tightly integrated with kernel ABI, NFS is network protocol.
  • Consequence: Code duplication in handler logic, but easier to optimize each for its use case (local vs. remote).

• Custom fuser fork instead of upstream crate

  • Why: Need for low-level FUSE control, deferred notification support, and agentfs-specific extensions.
  • Consequence: Maintenance burden and potential compatibility lag with newer F

Users need to ensure that they have FUSE installed on Linux systems for proper mounting. Also, certain dependencies like agentfs-sandbox require additional system libraries to compile successfully.

• FUSE (Filesystem in Userspace) — Understanding FUSE is essential for leveraging AgentFS on Linux to mount the filesystem correctly.
• SQLite database auditing — SQLite auditing is critical for understanding the versioning and state management features that AgentFS provides.
• Command-line interface (CLI) — The CLI implementation is crucial for user interaction and exposes the functionalities of AgentFS in a user-friendly manner.

• filecoin-project/go-filecoin — It provides similar functionalities for decentralized storage and filesystems.
• kubernetes-sigs/faker-provisioner — It offers a provisioning interface for managing filesystems in Kubernetes environments.
• tursodatabase/turso — This is a companion project aimed at providing database functionalities for AI workflows.
• facebookexperimental/reverie — It acts as a sandboxing tool essential for the experimental features of this file system.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for NFS server functionality in cli/src/cmd/nfs.rs

The NFS server is a core feature (nfs.rs exists and is referenced in Cargo.toml with nfsserve dependencies), but there's no corresponding test file visible in the structure. Given the complexity of network filesystem operations and multiple platform support (Linux/Darwin/Windows variants of run.rs exist), integration tests would catch regressions in NFS mount/unmount cycles, file operations over NFS, and cross-platform compatibility issues.

• [ ] Create cli/tests/nfs_integration_tests.rs
• [ ] Add tests for NFS mount operations covering basic file read/write, directory traversal, and permission handling
• [ ] Add platform-specific test cases for Linux (cli/tests/nfs_linux.rs) and macOS (cli/tests/nfs_darwin.rs)
• [ ] Update cli/Cargo.toml to include test dependencies if needed
• [ ] Document test execution in TESTING.md with NFS-specific instructions

Add GitHub Actions workflow to test Python SDK against multiple Python versions and platforms

The repo has .github/workflows/python.yml but the README shows PyPI badge indicating active Python SDK distribution. However, there's no visible multi-version Python test matrix (3.8, 3.9, 3.10, 3.11, 3.12) or cross-platform testing (Linux/macOS/Windows). This would catch Python compatibility regressions early and ensure SDK stability across environments where agents typically run.

• [ ] Review existing .github/workflows/python.yml and extend it with matrix strategy for python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
• [ ] Add matrix for os: [ubuntu-latest, macos-latest, windows-latest]
• [ ] Configure proper SDK path (sdk/python) for setup and test execution
• [ ] Add mypy type-checking step if not present
• [ ] Add step to verify SDK can be installed and imported correctly

Create comprehensive test coverage for FUSE implementation in cli/src/fuser/ with unit and syscall tests

The cli/perf/syscall/ directory contains performance test examples (perf-open-close.c, perf-statx.c) but the main FUSE implementation in cli/src/fuser/ (especially the low-level bindings in ll/ and mount logic in mnt/) lacks visible unit tests. Given the critical nature of FUSE for the core product and the vendored fuser dependencies, adding tests would prevent regressions in filesystem operations that agents depend on.

• [ ] Create cli/tests/fuse_unit_tests.rs covering cli/src/fuser/channel.rs lifecycle
• [ ] Create cli/tests/fuse_mount_tests.rs for cli/src/fuser/mnt/mount_options.rs configuration validation
• [ ] Add tests for cli/src/fuser/ll/request.rs and cli/src/fuser/ll/reply.rs message handling
• [ ] Create cli/tests/fuse_syscall_tests.rs extending cli/perf/syscall/ examples into repeatable test cases
• [ ] Update TESTING.md with section on running FUSE tests and platform requirements (libfuse-dev on Linux)

• Add unit tests for functions in cli/src/cmd/run.rs to enhance code coverage.
• Create documentation for the CLI commands in MANUAL.md not fully detailed.
• Refactor the syscall simulation scripts in cli/perf/syscall for improved performance and readability.

AgentFS has a moderate security posture with several areas of concern. The most critical issue is the use of unpinned Git dependencies and incomplete dependency specifications that could introduce supply chain vulnerabilities. The optional and platform-dependent sandbox feature poses a significant risk if not properly enabled by default. While the codebase appears to follow Rust best practices, the reliance on experimental sandboxing technology (reverie/ptrace) and the inclusion of an NFS server warrant careful security review. The project would benefit from: (1) pinning all Git dependencies to specific commits, (2) completing all dependency specifications, (3) making sandboxing mandatory on Linux, (4

• High · Git Dependency on External Repository — cli/Cargo.toml - reverie, reverie-ptrace, reverie-process dependencies. The Cargo.toml file includes dependencies from an external Git repository (https://github.com/facebookexperimental/reverie) without pinning to a specific commit hash. This allows for arbitrary code execution if the repository is compromised or changes unexpectedly. Fix: Pin Git dependencies to specific commit hashes using rev = "<commit_hash>" in Cargo.toml. Example: git = "https://github.com/facebookexperimental/reverie", rev = "abc123..."
• High · Incomplete Dependency Specification — cli/Cargo.toml - nix dependency. The nix dependency specification in Cargo.toml appears truncated (feat... is cut off), which may indicate incomplete or unvalidated configuration. This could lead to unexpected behavior or missing security features. Fix: Complete and verify all dependency specifications, ensuring all required features are explicitly listed.
• Medium · Sandbox Feature Disabled by Default on Non-Linux — cli/Cargo.toml - sandbox feature configuration. The sandbox feature (which provides security isolation) is only available on Linux systems. On macOS and Windows, the sandbox is not available, potentially exposing agents to unrestricted system access. Fix: Document sandbox limitations clearly. Consider implementing alternative security controls for non-Linux platforms or warn users about the reduced security posture.
• Medium · Optional Sandbox Dependencies — cli/Cargo.toml - features configuration. Sandbox functionality is optional and requires manual feature enablement. Users may unknowingly deploy AgentFS without security sandboxing enabled, exposing the system to untrusted agent code. Fix: Make the sandbox feature enabled by default (move from optional to mandatory on Linux). Document the security implications of running without sandboxing.
• Medium · Ptrace-Based Sandboxing Risks — cli/Cargo.toml - reverie-ptrace dependency. The sandbox relies on ptrace (process tracing) via reverie. Ptrace-based sandboxing has known limitations and can be bypassed. Additionally, reverie is an experimental project. Fix: Conduct thorough security audits of the sandboxing implementation. Document ptrace limitations. Consider additional defense-in-depth mechanisms.
• Low · Unverified Upstream Dependencies — cli/Cargo.toml - all dependencies. While major dependencies (tokio, serde, clap) are from reputable sources, the transitive dependency tree is not explicitly controlled, increasing supply chain attack surface. Fix: Use cargo-deny or similar tools to audit dependencies. Generate and review SBOM (Software Bill of Materials). Consider vendoring critical dependencies.
• Low · Permissive Dependency Versions — cli/Cargo.toml - dependency version specifications. Many dependencies use caret (^) versioning, allowing for minor and patch updates without explicit review. While generally safe, this could introduce unexpected changes. Fix: Consider using more restrictive version constraints (=) for security-critical dependencies. Implement automated security scanning in CI/CD.
• Low · NFS Server Exposure — cli/src/nfsserve/ directory. The codebase includes an NFS server implementation (nfsserve). NFS has known security limitations and is vulnerable to network-based attacks if exposed. Fix: Ensure NFS is only exposed on trusted networks. Implement strong authentication and encryption (Kerberos, TLS). Document NFS security limitations.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.