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.
FilesystemBackend(
self,
root_dir: str | Path | None = None,
virtual_mode: bool | None = None,
max_file_size_mb: int = 10
)| Name | Type | Description |
|---|---|---|
root_dir | str | Path | None | Default: NoneOptional root directory for file operations. Defaults to the current working directory.
|
virtual_mode | bool | None | Default: NoneEnable virtual path mode. Primary use case: stable, backend-independent path semantics when
used with When When
|
max_file_size_mb | int | Default: 10Maximum file size in megabytes for operations like grep's Python fallback search. Files exceeding this limit are skipped during search. Defaults to 10 MB. |
List files and directories in the specified directory (non-recursive).
Read file content with line numbers.
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.
Async version of ls_info.
Async version of read using native store async methods.
Async version of grep_raw.
Async version of glob_info.
Async version of write using native store async methods.
Async version of edit using native store async methods.
Async version of upload_files.
Async version of download_files.