LocalShellBackend: Filesystem backend with unrestricted local shell execution.
This backend extends FilesystemBackend to add shell command execution on the local host system. It provides NO sandboxing or isolation - all operations run directly on the host machine with full system access.
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.
Result of code execution.
Simplified schema optimized for LLM consumption.
Extension of BackendProtocol that adds shell command execution.
Designed for backends running in isolated environments (containers, VMs, remote hosts).
Adds execute()/aexecute() for shell commands and an id property.
See BaseSandbox for a base class that implements all inherited file
operations by delegating to execute().
Filesystem backend with unrestricted local shell command execution.
This backend extends FilesystemBackend to add shell command execution
capabilities. Commands are executed directly on the host system without any
sandboxing, process isolation, or security restrictions.
This backend grants agents BOTH direct filesystem access AND unrestricted shell execution on your local machine. Use with extreme caution and only in appropriate environments.
Appropriate use cases:
Inappropriate use cases:
Use StateBackend, StoreBackend, or extend BaseSandbox for production.
Security risks:
.env files, SSH keys, etc.)Recommended safeguards:
Since shell access is unrestricted and can bypass filesystem restrictions:
BaseSandbox
to create a properly isolated backend (Docker containers, VMs, or other
sandboxed execution environments)virtual_mode=True and path-based restrictions provide NO security
with shell access enabled, since commands can access any path on the system