What You Can Do
- Run Any Shell Command: Execute standard commands like
ls,grep,curl, orgit. - Execute Scripts: Run shell scripts (
.sh) or other command-line scripts. - Manage System Processes: Check running processes, manage services, or gather system information.
- Choose Your Environment: Run commands directly on the local machine for speed or in a secure sandbox for safety.
Core Concepts
BashTool: The main tool you provide to your agent. It takes a shell command as input and executes it.BashOperator(Backend): The engine that runs the command. You can choose from two backends:LocalBashOperator: Executes commands directly on the host machine. It’s fast but should only be used in trusted environments.SandboxBashOperator: Executes commands inside a secure, isolated E2B container. It’s the safe choice for handling commands generated by LLMs or users.
Quick Start
Choosing the Right Backend
| Backend | Use Case | Key Benefit |
|---|---|---|
LocalBashOperator | Trusted Scripts & Dev | Performance & Local Access |
SandboxBashOperator | Untrusted Commands (LLMs) | Security & Isolation |
Core Operations & Examples
Running a Simple Command
Execute any standard shell command and get thestdout, stderr, and exitCode.
Piping Commands
Chain commands together using pipes, just like in a regular shell.Streaming Output
For long-running commands likenpm install or a development server, you can stream stdout and stderr in real-time instead of waiting for the command to finish. This is done by providing onStdout and onStderr handlers when creating the operator.
Best Practices & Troubleshooting
- Prefer Specific Tools: If a dedicated tool exists (like the
lsorgreptools inFilesystemToolkit), prefer it over the rawbashcommand. Dedicated tools often provide structured output and better error handling. - Security: Never use the
LocalBashOperatorwith commands generated by an LLM or external users. Always use theSandboxBashOperatorfor untrusted input. - Error Handling: Always check the
exitCodeandstderrfrom the result to know if a command failed and why. - Working Directory: Be mindful of the current working directory (
cwd). Commands are executed relative to it. You can set thecwdwhen creating theBashOperator.