Skip to main content

bash

Run real shell commands from the agent's workdir - npm, git, python, build tools, anything a developer would type. Shell state (cwd, env, activated venvs) persists across calls within a session, like a real terminal.

Exact tools and parameters

catalog.describe_module bash returns the real tool and every parameter, from the live registry. Use it instead of trusting a list here.

Tool, at a glance: run.

Gotchas that matter​

  • Long-running processes (dev servers, watchers, tail -f, REPLs) must use background_run (a context_builder tool), never a foreground bash.run - a foreground long-runner freezes the turn until timeout. Never append a trailing &.
  • pty: true for commands that need a real terminal (docker run -it, ssh, npm login).
  • run is RiskHigh and irreversible - gate it with tools.capabilities.approve if the app should confirm before running.

A working app​

Compiles as-is. The brain uses a Digitorn gateway model (the default - no API key of your own needed); see the note below to use your own key or a local model instead.

yaml
app:
  app_id: shell_runner
  name: Shell Runner
runtime:
  entry_agent: main
agents:
  - id: main
    system_prompt: |
      Run shell commands to build and inspect the project. Use background_run
      for long-lived processes like dev servers, never a foreground command.
    brain:
      provider: openai
      backend: openai_compat
      model: mimo-v2.5-free   # a model the Digitorn gateway serves
      config:
        api_key: placeholder  # ignored in gateway mode
tools:
  modules:
    bash: {}
  capabilities:
    grant:
      - module: bash
        tools: [run]