Skip to main content
The shell tool allows agents to execute arbitrary shell commands. It is one of the most powerful built-in tools — it lets agents run builds, install dependencies, query the system, and automate any task expressible as a shell command. Each call runs in a fresh, isolated shell session. No state (environment variables, working directory changes) persists between separate shell calls.

​
Available tools

ToolDescription
shellExecute a shell command and return its combined stdout/stderr output.
run_background_jobStart a long-running command in the background and return a job ID immediately.
list_background_jobsList all background jobs with their status and runtime.
view_background_jobView the live output or final result of a background job by ID.
stop_background_jobCancel a running background job by ID.

​
Configuration

toolsets:
  - type: shell

​
Options

​
env
object
Environment variables to inject into every shell command. Values can reference existing environment variables using ${VAR} syntax.

​
Custom environment variables

toolsets:
  - type: shell
    env:
      NODE_ENV: production
      PATH: "${PATH}:/home/user/.local/bin"
      API_BASE_URL: "https://api.example.com"

​
Shell tool parameters

When the agent calls the shell tool, it passes these parameters:
ParameterTypeRequiredDescription
cmdstringYesThe shell command to execute.
cwdstringNoWorking directory for this command. Defaults to the agent’s working directory.
timeoutintegerNoPer-call timeout in seconds. Overrides the default 30-second timeout.

​
Background jobs

Use run_background_job for long-running processes like dev servers, file watchers, or build daemons. The agent can start the job and continue with other tasks while it runs.
agent.yaml
agents:
  root:
    model: openai/gpt-4o
    description: Full-stack developer
    instruction: |
      You can start dev servers in the background while working on code.
      Use run_background_job for servers and watchers.
    toolsets:
      - type: shell
      - type: filesystem
All background jobs are automatically terminated when the agent stops. Output per job is capped at 10 MB.

​
Example agent

agent.yaml
agents:
  root:
    model: openai/gpt-4o
    description: Build and test assistant
    instruction: |
      Help the user run builds, tests, and linting.
      Use the shell tool to execute commands.
      Use cwd to run commands in the right directory.
    toolsets:
      - type: shell
        env:
          GOFLAGS: "-mod=mod"
      - type: filesystem
By default, Docker Agent asks for confirmation before executing shell commands. Use --yolo to auto-approve all tool calls without prompts — useful for automated workflows:
docker agent run agent.yaml --yolo

​
Security considerations

The shell tool gives the agent full access to the system shell. Apply these safeguards:
  • Set max_iterations on the agent (20–50 is typical) to prevent runaway loops.
  • Use Sandbox Mode to run the agent in an isolated container.
  • Use Permissions to require confirmation before destructive commands.
  • Use the env option to inject credentials rather than having the agent read them from files.

Script

Expose predefined commands as named tools with typed parameters.

Filesystem

Read and write files alongside shell operations.

Sandbox

Run agents in isolated Docker containers.

Permissions

Control which commands require confirmation.

Build docs developers (and LLMs) love

Get started for freeTalk to us