https://cruvero.ai/assets/js/e5a779ca.1f7a811f.js

1"use strict";(globalThis.webpackChunksite=globalThis.webpackChunksite||[]).push([[2833],{10178(e,n,s){s.r(n),s.d(n,{assets:()=>t,contentTitle:()=>o,default:()=>h,frontMatter:()=>c,metadata:()=>i,toc:()=>r});const i=JSON.parse('{"id":"bash-exec","title":"Bash Exec","description":"The `bash_exec` tool executes bash commands inside a constrained sandbox. It is intended for controlled shell automation with a command allowlist, timeo...","source":"@site/docs/develop/bash-exec.md","sourceDirName":".","slug":"/bash-exec","permalink":"/develop/bash-exec","draft":false,"unlisted":false,"editUrl":"https://github.com/roygabriel/cruvero/tree/dev/docs/develop/bash-exec.md","tags":[],"version":"current","frontMatter":{"title":"Bash Exec","description":"The `bash_exec` tool executes bash commands inside a constrained sandbox. It is intended for controlled shell automation with a command allowlist, timeo...","source_path":"docs/manual/bash-exec.md","generated":true},"sidebar":"developSidebar","previous":{"title":"Python Exec","permalink":"/develop/python-exec"},"next":{"title":"Tool Registry Restructure","permalink":"/develop/tool-registry-restructure"}}');var d=s(74848),l=s(28453);const c={title:"Bash Exec",description:"The `bash_exec` tool executes bash commands inside a constrained sandbox. It is intended for controlled shell automation with a command allowlist, timeo...",source_path:"docs/manual/bash-exec.md",generated:!0},o="Bash Exec Tool",t={},r=[{value:"Schema",id:"schema",level:2},{value:"Output",id:"output",level:2},{value:"Sandbox Limits",id:"sandbox-limits",level:2},{value:"Command Allowlist",id:"command-allowlist",level:2},{value:"Environment Overrides",id:"environment-overrides",level:2},{value:"Security Notes",id:"security-notes",level:2},{value:"Audit Log",id:"audit-log",level:2},{value:"Related Docs",id:"related-docs",level:2}];function a(e){const n={a:"a",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",header:"header",li:"li",p:"p",pre:"pre",ul:"ul",...(0,l.R)(),...e.components};return(0,d.jsxs)(d.Fragment,{children:[(0,d.jsxs)(n.blockquote,{children:["\n",(0,d.jsxs)(n.p,{children:["Source: ",(0,d.jsx)(n.a,{href:"https://github.com/cruvero/cruvero-platform/blob/main/docs/manual/bash-exec.md",children:(0,d.jsx)(n.code,{children:"docs/manual/bash-exec.md"})})]}),"\n",(0,d.jsxs)(n.p,{children:["This page is generated by ",(0,d.jsx)(n.code,{children:"site/scripts/sync-manual-docs.mjs"}),"."]}),"\n"]}),"\n",(0,d.jsx)(n.header,{children:(0,d.jsx)(n.h1,{id:"bash-exec-tool",children:"Bash Exec Tool"})}),"\n",(0,d.jsxs)(n.p,{children:["The ",(0,d.jsx)(n.code,{children:"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."]}),"\n",(0,d.jsx)(n.h2,{id:"schema",children:"Schema"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-json",children:'{\n  "type": "object",\n  "required": ["command"],\n  "properties": {\n    "command": {"type": "string", "description": "Bash command or script to execute."},\n    "timeout_ms": {"type": "integer", "description": "Timeout in milliseconds (default 2000)."},\n    "env": {"type": "object", "description": "Optional environment variables."},\n    "allow_network": {"type": "boolean", "description": "Allow network commands if enabled by env."},\n    "max_output_kb": {"type": "integer", "description": "Override stdout/stderr limit in KB (bounded)."},\n    "max_file_kb": {"type": "integer", "description": "Override max file size in KB (bounded)."},\n    "files": {\n      "type": "array",\n      "items": {\n        "type": "object",\n        "required": ["path", "content"],\n        "properties": {\n          "path": {"type": "string"},\n          "content": {"type": "string"}\n        },\n        "additionalProperties": false\n      }\n    }\n  },\n  "additionalProperties": false\n}\n'})}),"\n",(0,d.jsx)(n.h2,{id:"output",children:"Output"}),"\n",(0,d.jsx)(n.p,{children:"The tool returns JSON with:"}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"stdout"})," (string)"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"stderr"})," (string)"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"exit_code"})," (int)"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"result_json"})," (optional JSON) extracted from a ",(0,d.jsx)(n.code,{children:"__RESULT__:{...}"})," line in stdout."]}),"\n"]}),"\n",(0,d.jsx)(n.p,{children:"Example:"}),"\n",(0,d.jsx)(n.pre,{children:(0,d.jsx)(n.code,{className:"language-bash",children:'echo \'__RESULT__:{\\"status\\":\\"ok\\",\\"count\\":3}\'\n'})}),"\n",(0,d.jsx)(n.h2,{id:"sandbox-limits",children:"Sandbox Limits"}),"\n",(0,d.jsx)(n.p,{children:"Defaults (configurable in env):"}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsxs)(n.li,{children:["Timeout: 2 seconds (",(0,d.jsx)(n.code,{children:"timeout_ms"})," overrides per call)"]}),"\n",(0,d.jsx)(n.li,{children:"Stdout/Stderr: 64 KB total each"}),"\n",(0,d.jsx)(n.li,{children:"File content size: 256 KB per file"}),"\n"]}),"\n",(0,d.jsxs)(n.p,{children:["Network access is blocked by default. The working directory is a temp folder under ",(0,d.jsx)(n.code,{children:"HOME"}),".\nExecution is routed through ",(0,d.jsx)(n.code,{children:"CRUVERO_SANDBOX_MODE"})," (",(0,d.jsx)(n.code,{children:"process|gvisor|nsjail"}),") with automatic fallback to ",(0,d.jsx)(n.code,{children:"process"})," when the selected runtime is unavailable."]}),"\n",(0,d.jsx)(n.h2,{id:"command-allowlist",children:"Command Allowlist"}),"\n",(0,d.jsx)(n.p,{children:"Only allowlisted commands are available. If a command is not allowlisted, the tool returns an error with the allowed list."}),"\n",(0,d.jsx)(n.p,{children:"Default allowlist:"}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"awk"}),", ",(0,d.jsx)(n.code,{children:"basename"}),", ",(0,d.jsx)(n.code,{children:"cat"}),", ",(0,d.jsx)(n.code,{children:"cut"}),", ",(0,d.jsx)(n.code,{children:"date"}),", ",(0,d.jsx)(n.code,{children:"dirname"}),", ",(0,d.jsx)(n.code,{children:"echo"}),", ",(0,d.jsx)(n.code,{children:"env"}),", ",(0,d.jsx)(n.code,{children:"find"})]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"grep"}),", ",(0,d.jsx)(n.code,{children:"head"}),", ",(0,d.jsx)(n.code,{children:"jq"}),", ",(0,d.jsx)(n.code,{children:"ls"}),", ",(0,d.jsx)(n.code,{children:"printf"}),", ",(0,d.jsx)(n.code,{children:"pwd"}),", ",(0,d.jsx)(n.code,{children:"rg"}),", ",(0,d.jsx)(n.code,{children:"sed"}),", ",(0,d.jsx)(n.code,{children:"sort"})]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"tail"}),", ",(0,d.jsx)(n.code,{children:"tr"}),", ",(0,d.jsx)(n.code,{children:"uniq"}),", ",(0,d.jsx)(n.code,{children:"wc"}),", ",(0,d.jsx)(n.code,{children:"xargs"}),", ",(0,d.jsx)(n.code,{children:"sleep"}),", ",(0,d.jsx)(n.code,{children:"stat"}),", ",(0,d.jsx)(n.code,{children:"test"}),", ",(0,d.jsx)(n.code,{children:"true"})]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"false"}),", ",(0,d.jsx)(n.code,{children:"mkdir"}),", ",(0,d.jsx)(n.code,{children:"rm"}),", ",(0,d.jsx)(n.code,{children:"cp"}),", ",(0,d.jsx)(n.code,{children:"mv"}),", ",(0,d.jsx)(n.code,{children:"touch"})]}),"\n"]}

1),"\n",(0,d.jsxs)(n.p,{children:["Network allowlist (enabled only when ",(0,d.jsx)(n.code,{children:"CRUVERO_BASH_ALLOW_NETWORK=true"})," and ",(0,d.jsx)(n.code,{children:"allow_network=true"}),"):"]}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"curl"}),", ",(0,d.jsx)(n.code,{children:"wget"}),", ",(0,d.jsx)(n.code,{children:"ping"}),", ",(0,d.jsx)(n.code,{children:"nslookup"}),", ",(0,d.jsx)(n.code,{children:"dig"}),", ",(0,d.jsx)(n.code,{children:"ssh"}),", ",(0,d.jsx)(n.code,{children:"scp"}),", ",(0,d.jsx)(n.code,{children:"git"})]}),"\n"]}),"\n",(0,d.jsx)(n.h2,{id:"environment-overrides",children:"Environment Overrides"}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"CRUVERO_BASH_ALLOWED_CMDS"})," (comma-separated allowlist)"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"CRUVERO_BASH_ALLOW_NETWORK"})," (default ",(0,d.jsx)(n.code,{children:"false"}),")"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"CRUVERO_BASH_MAX_OUTPUT_KB"})," (default ",(0,d.jsx)(n.code,{children:"64"}),")"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"CRUVERO_BASH_MAX_FILE_KB"})," (default ",(0,d.jsx)(n.code,{children:"256"}),")"]}),"\n",(0,d.jsxs)(n.li,{children:[(0,d.jsx)(n.code,{children:"CRUVERO_SANDBOX_MODE"})," (",(0,d.jsx)(n.code,{children:"process|gvisor|nsjail"}),", default ",(0,d.jsx)(n.code,{children:"process"}),")"]}),"\n"]}),"\n",(0,d.jsx)(n.h2,{id:"security-notes",children:"Security Notes"}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsx)(n.li,{children:"Commands not in the allowlist are rejected before execution."}),"\n",(0,d.jsx)(n.li,{children:"Network commands are blocked unless explicitly enabled in env and per-call."}),"\n",(0,d.jsx)(n.li,{children:"Output and file sizes are capped."}),"\n"]}),"\n",(0,d.jsx)(n.h2,{id:"audit-log",children:"Audit Log"}),"\n",(0,d.jsxs)(n.p,{children:["Each ",(0,d.jsx)(n.code,{children:"bash_exec"})," run writes a memory episode of type ",(0,d.jsx)(n.code,{children:"bash_audit"})," with command, exit code, sizes, and duration. Use ",(0,d.jsx)(n.code,{children:"cmd/memory-query --type episodic --run-id <id>"})," to inspect."]}),"\n",(0,d.jsx)(n.h2,{id:"related-docs",children:"Related Docs"}),"\n",(0,d.jsxs)(n.ul,{children:["\n",(0,d.jsx)(n.li,{children:(0,d.jsx)(n.a,{href:"/develop/tools-and-registry",children:"Tools and Registry"})}),"\n",(0,d.jsx)(n.li,{children:(0,d.jsx)(n.a,{href:"/develop/testing-and-fixtures",children:"Testing and Fixtures"})}),"\n"]})]})}function h(e={}){const{wrapper:n}={...(0,l.R)(),...e.components};return n?(0,d.jsx)(n,{...e,children:(0,d.jsx)(a,{...e})}):a(e)}},28453(e,n,s){s.d(n,{R:()=>c,x:()=>o});var i=s(96540);const d={},l=i.createContext(d);function c(e){const n=i.useContext(l);return i.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(d):e.components||d:c(e.components),i.createElement(l.Provider,{value:n},e.children)}}}]);