Skip to main content

Source: docs/manual/bash-exec.md

This page is generated by site/scripts/sync-manual-docs.mjs.

Bash Exec Tool

The bash_exec tool executes bash commands inside a constrained sandbox. It is intended for controlled shell automation with a command allowlist, timeouts, and output limits.

Schema​

{
  "type": "object",
  "required": ["command"],
  "properties": {
    "command": {"type": "string", "description": "Bash command or script to execute."},
    "timeout_ms": {"type": "integer", "description": "Timeout in milliseconds (default 2000)."},
    "env": {"type": "object", "description": "Optional environment variables."},
    "allow_network": {"type": "boolean", "description": "Allow network commands if enabled by env."},
    "max_output_kb": {"type": "integer", "description": "Override stdout/stderr limit in KB (bounded)."},
    "max_file_kb": {"type": "integer", "description": "Override max file size in KB (bounded)."},
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["path", "content"],
        "properties": {
          "path": {"type": "string"},
          "content": {"type": "string"}
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

Output​

The tool returns JSON with:

  • stdout (string)
  • stderr (string)
  • exit_code (int)
  • result_json (optional JSON) extracted from a __RESULT__:{...} line in stdout.

Example:

echo '__RESULT__:{\"status\":\"ok\",\"count\":3}'

Sandbox Limits​

Defaults (configurable in env):

  • Timeout: 2 seconds (timeout_ms overrides per call)
  • Stdout/Stderr: 64 KB total each
  • File content size: 256 KB per file

Network access is blocked by default. The working directory is a temp folder under HOME. Execution is routed through CRUVERO_SANDBOX_MODE (process|gvisor|nsjail) with automatic fallback to process when the selected runtime is unavailable.

Command Allowlist​

Only allowlisted commands are available. If a command is not allowlisted, the tool returns an error with the allowed list.

Default allowlist:

  • awk, basename, cat, cut, date, dirname, echo, env, find
  • grep, head, jq, ls, printf, pwd, rg, sed, sort
  • tail, tr, uniq, wc, xargs, sleep, stat, test, true
  • false, mkdir, rm, cp, mv, touch

Network allowlist (enabled only when CRUVERO_BASH_ALLOW_NETWORK=true and allow_network=true):

  • curl, wget, ping, nslookup, dig, ssh, scp, git

Environment Overrides​

  • CRUVERO_BASH_ALLOWED_CMDS (comma-separated allowlist)
  • CRUVERO_BASH_ALLOW_NETWORK (default false)
  • CRUVERO_BASH_MAX_OUTPUT_KB (default 64)
  • CRUVERO_BASH_MAX_FILE_KB (default 256)
  • CRUVERO_SANDBOX_MODE (process|gvisor|nsjail, default process)

Security Notes​

  • Commands not in the allowlist are rejected before execution.
  • Network commands are blocked unless explicitly enabled in env and per-call.
  • Output and file sizes are capped.

Audit Log​

Each bash_exec run writes a memory episode of type bash_audit with command, exit code, sizes, and duration. Use cmd/memory-query --type episodic --run-id <id> to inspect.