Shell Tool
Execute arbitrary shell commands in the user’s environment.
Overview
The shell tool allows agents to execute arbitrary shell commands. This is one of the most powerful tools — it lets agents run builds, install dependencies, query APIs, and interact with the system. Each call runs in a fresh, isolated shell session — no state persists between calls.
Commands have a default 30-second timeout and require user confirmation unless --yolo is used.
Configuration
toolsets:
- type: shell
Options
| Property | Type | Description |
|---|---|---|
env |
object | Environment variables to set for all shell commands |
Custom Environment Variables
toolsets:
- type: shell
env:
MY_VAR: "value"
PATH: "${PATH}:/custom/bin"
The shell tool gives agents full access to the system shell. Always set max_iterations on agents that use the shell tool to prevent infinite loops. A value of 20–50 is typical for development agents. Use Sandbox Mode for additional isolation.
By default, docker-agent asks for user confirmation before executing shell commands. Use --yolo to auto-approve all tool calls.