FilesystemBackend(
self,
root_dirAsync version of ls.
Async version of read.
Async version of grep.
Async version of glob.
Async version of write.
Async version of edit.
Async version of upload_files.
Async version of download_files.
List all files in a directory with metadata.
Async version of ls_info.
Find files matching a glob pattern.
Async version of glob_info.
Search for a literal text pattern in files.
Async version of grep_raw.
Backend that reads and writes files directly from the filesystem.
Files are accessed using their actual filesystem paths. Relative paths are resolved relative to the current working directory. Content is read/written as plain text, and metadata (timestamps) are derived from filesystem stats.
This backend grants agents direct filesystem read/write access. Use with caution and only in appropriate environments.
Appropriate use cases:
Inappropriate use cases:
StateBackend, StoreBackend, or
SandboxBackend insteadSecurity risks:
.env files)Recommended safeguards:
StateBackend, StoreBackend or SandboxBackendIn general, we expect this backend to be used with Human-in-the-Loop (HITL) middleware, or within a properly sandboxed environment if you need to run untrusted workloads.
virtual_mode=True is primarily for virtual path semantics (for example with
CompositeBackend). It can also provide path-based guardrails by blocking
traversal (.., ~) and absolute paths outside root_dir, but it does not
provide sandboxing or process isolation. The default (virtual_mode=False)
provides no security even with root_dir set.
10Optional root directory for file operations.
Defaults to the current working directory.
virtual_mode=False (default): Only affects relative path resolution.virtual_mode=True: Acts as a virtual root for filesystem operations.Enable virtual path mode.
Primary use case: stable, backend-independent path semantics when
used with CompositeBackend, which strips route prefixes and forwards
normalized paths to the routed backend.
When True, all paths are treated as virtual paths anchored to
root_dir. Path traversal (.., ~) is blocked and all resolved paths
are verified to remain within root_dir.
When False (default), absolute paths are used as-is and relative paths
are resolved under root_dir. This provides no security against an agent
choosing paths outside root_dir.
/etc/passwd) bypass root_dir entirely.. can escape root_dirList files and directories in the specified directory (non-recursive).
Read file content for the requested line range.
Create a new file with content.
Edit a file by replacing string occurrences.
Search for a literal text pattern in files.
Uses ripgrep if available, falling back to Python search.
Find files matching a glob pattern.
Upload multiple files to the filesystem.
Download multiple files from the filesystem.
Maximum file size in megabytes for operations like grep's Python fallback search.
Files exceeding this limit are skipped during search. Defaults to 10 MB.