LocalShellBackend
LocalShellBackend(
self,
Inherited fromFilesystemBackend
Methods
List files and directories in the specified directory (non-recursive).
Read file content for the requested line range.
Write content to a file, creating it or overwriting it if it already exists.
Edit a file by replacing string occurrences.
Delete a file or directory from the filesystem.
Search for a literal text pattern in files.
Async version of grep, with optional surrounding context lines.
Find files matching a glob pattern.
Upload multiple files to the filesystem.
Download multiple files from the filesystem.
Inherited fromSandboxBackendProtocol
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:
- Local development CLIs (coding assistants, development tools)
- Personal development environments where you trust the agent's code
- CI/CD pipelines with proper secret management (see security considerations)
Inappropriate use cases:
- Production environments (e.g., web servers, APIs, multi-tenant systems)
- Processing untrusted user input or executing untrusted code
Use StateBackend, StoreBackend, or extend BaseSandbox for production.
Security risks:
- Agents can execute arbitrary shell commands with your user's permissions
- Agents can read any accessible file, including secrets (API keys,
credentials,
.envfiles, SSH keys, etc.) - Combined with network tools, secrets may be exfiltrated via SSRF attacks
- File modifications and command execution are permanent and irreversible
- Agents can install packages, modify system files, spawn processes, etc.
- No process isolation - commands run directly on your host system
- No resource limits - commands can consume unlimited CPU, memory, disk
Recommended safeguards:
Since shell access is unrestricted and can bypass filesystem restrictions:
- Enable Human-in-the-Loop (HITL) middleware to review and approve ALL operations before execution. This is STRONGLY RECOMMENDED as your primary safeguard when using this backend.
- Run in dedicated development environments only - never on shared or production systems
- Never expose to untrusted users or allow execution of untrusted code
- For production environments requiring code execution, extend
BaseSandboxto 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.
DEFAULT_EXECUTE_TIMEOUTmax_output_bytes | int | Default: 100000 |
env | dict[str, str] | None | Default: None |
inherit_env | bool | Default: False |
Working directory for both filesystem operations and shell commands.
-
If not provided, defaults to the current working directory.
-
Shell commands execute with this as their working directory.
-
When
virtual_mode=False: Paths are used as-is.Agents can access any file using absolute paths or
..sequences. -
When
virtual_mode=True(default): Acts as a virtual root for filesystem operations.Useful with
CompositeBackendto support routing file operations across different backend implementations.Note: This does NOT restrict shell commands.
Enable virtual path mode for filesystem operations.
When True (default), 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:
- Access any file on the filesystem (regardless of
virtual_mode) - Execute any program or script
- Make network connections
- Modify system configuration
- Spawn additional processes
- Install packages or modify dependencies
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.