LocalShellBackend(
self,
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 store files for a literal text pattern.
Find files matching a glob pattern in the store.
Upload multiple files to the store.
Download multiple files from the store.
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
Async version of read using native store async methods.
DEFAULT_EXECUTE_TIMEOUTmax_output_bytes | int | Default: 100000 |
env | dict[str, str] | None | Default: None |
inherit_env | bool | Default: False |
| inherit_env | bool |
Working directory for both filesystem operations and shell commands.
virtual_mode=False (default): Paths are used as-is. Agents can
access any file using absolute paths or .. sequences.virtual_mode=True: Acts as a virtual root for filesystem operations.
Useful with CompositeBackend to support routing file operations across
different backend implementations. Note: This does NOT restrict shell
commands.Enable virtual path mode for filesystem operations.
When True, treats root_dir as a virtual root filesystem. All paths
are interpreted relative to root_dir (e.g., /file.txt maps to
{root_dir}/file.txt). Path traversal (.., ~) is blocked.
Primary use case: Working with CompositeBackend, which routes
different path prefixes to different backends. Virtual mode allows the
CompositeBackend to strip route prefixes and pass normalized paths to
each backend, enabling file operations to work correctly across multiple
backend implementations.
Important: This only affects filesystem operations. Shell commands
executed via execute() are NOT restricted and can access any path.
Unique identifier for this backend instance.
Execute a shell command directly on the host system.
Commands are executed directly on your host system using subprocess.run()
with shell=True. There is no sandboxing, isolation, or security
restrictions. The command runs with your user's full permissions and can:
virtual_mode)Always use Human-in-the-Loop (HITL) middleware when using this method.
The command is executed using the system shell (/bin/sh or equivalent) with
the working directory set to the backend's root_dir. Stdout and stderr are
combined into a single output stream.
Default maximum time in seconds to wait for shell command execution.
Defaults to 120 seconds (2 minutes).
Commands exceeding this timeout will be terminated.
Can be overridden per-command via the timeout parameter on execute().
Maximum number of bytes to capture from command output. Output exceeding this limit will be truncated. Defaults to 100,000 bytes.
Environment variables for shell commands. If None, starts with an empty
environment (unless inherit_env=True).
Whether to inherit the parent process's environment variables.
When False (default), only variables in env dict are available.
When True, inherits all os.environ variables and applies env overrides.