Skip to main content

Exec

exec is one of the core runtime tools in MushroomAgent. It runs shell commands locally and can either return immediately or hand off long-running work to process.

What it does​

  • run one-off commands
  • support workdir and environment overrides
  • support timeouts and output truncation
  • support background for long-running tasks
  • share background sessions with process

Parameters​

ParameterDescription
commandcommand to execute, required
workdirworking directory, supports relative paths
envJSON object of environment overrides
timeouttimeout in seconds, defaults to tools.exec.default_timeout
max_output_charsmaximum returned output length
backgroundrun command in the background and return a session id immediately

Execution model​

  • without shell operators, the command is parsed directly as argv
  • with pipes, redirects, or variable expansion, falls back to /bin/sh -lc
  • allowlist matches by command name or basename by default
  • when privileged=false, commands not in the allowlist return capability_limited

Config​

tools:
  exec:
    enabled: true
    cwd: /absolute/path/to/workspace
    cwd_root: /absolute/path/to/workspace
    allowlist:
      - curl
      - python3
      - ls
      - rg
      - cat
      - pwd
    privileged: false
    default_timeout: 1800
    max_output_chars: 200000

mushroom-agent init enables exec by default with a baseline allowlist.

Examples​

Foreground execution:

{ "tool": "exec", "command": "rg TODO ." }

Background execution:

{ "tool": "exec", "command": "npm run dev", "background": true }