Execute shell commands with timeout, output limits, and command allowlisting.
Execute shell commands from your agent. Supports timeouts, output truncation, and an optional command allowlist for safety.
Quick Start
import { Agent, openai } from "@agentium/core";import { ShellToolkit } from "@agentium/core/toolkits";const shell = new ShellToolkit({ timeout: 10_000, allowedCommands: ["ls", "cat", "grep", "find", "wc"],});const agent = new Agent({ name: "devops-agent", model: openai(process.env.OPENAI_MODEL ?? "gpt-6.1-sol"), instructions: "Help users inspect their system and files.", tools: [...shell.getTools()],});const result = await agent.run("How many TypeScript files are in the src directory?");
Config
string
Shell to use (default: platform default, e.g. /bin/sh).
number
default:"30000"
Command timeout in milliseconds.
number
default:"10000"
Max output characters to return. Long output is truncated from the start.
string
Working directory for commands.
string[]
Allowlist of command prefixes. If set, only commands starting with one of these are permitted.
Tools
Tool
Description
shell_exec
Execute a shell command. Returns stdout, stderr, and exit code.
Security
The Shell toolkit includes built-in protections against command injection:
Metacharacter rejection: Commands containing shell metacharacters (;, |, &, `, $, (, ), {, }, \, <, >, newlines) are automatically rejected before execution — even if they pass the allowlist check.
Allowlist enforcement: When allowedCommands is set, only commands starting with an allowed prefix are permitted.
These protections prevent an LLM from chaining commands, piping to other processes, or using shell expansion in arguments.
Always set allowedCommands in production to restrict which commands agents can run. Without it, the agent can execute any single command (subject to metacharacter validation).
See the Security page for a full overview of security hardening across Agentium.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Agentium","colors":{"primary":"#2563EB","light":"#3B82F6","dark":"#1E40AF"},"logo":{"light":"https://mintcdn.com/xhipment/Ed5pO8kvbGYPhMpL/logo/light.svg?fit=max\u0026auto=format\u0026n=Ed5pO8kvbGYPhMpL\u0026q=85\u0026s=78e27fa90cb7eeca27547aec06e58eb6","dark":"https://mintcdn.com/xhipment/Ed5pO8kvbGYPhMpL/logo/dark.svg?fit=max\u0026auto=format\u0026n=Ed5pO8kvbGYPhMpL\u0026q=85\u0026s=abff624f5ecdb6247595c779b4f6a0d9"},"favicon":"https://mintcdn.com/xhipment/BEAHuQmH5n29YrcC/favicon.svg?fit=max\u0026auto=format\u0026n=BEAHuQmH5n29YrcC\u0026q=85\u0026s=3c0a399371709ca5b6222be8277d7154","navbar":{"links":[{"href":"https://github.com/agentiumOS/agentium","label":"GitHub"}]},"footer":{"socials":{"github":"https://github.com/agentiumOS/agentium"}},"banner":{"content":"Agentium 4.11.0 is available · [Release and upgrade guidance](/reference/releases).","dismissible":true},"contextual":{"options":["copy","view","chatgpt","claude","cursor"],"display":"header"},"styling":{"latex":true},"navigation":{"global":{"anchors":[{"anchor":"GitHub","icon":"github","href":"https://github.com/agentiumOS/agentium"},{"anchor":"npm","icon":"npm","href":"https://www.npmjs.com/org/agentium"}]},"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"xhipment","hasAudioNarration":false,"actualSubdomain":"xhipment","customDomains":["docs.agentium.in"],"gitSource":{"type":"github","owner":"agentiumos","repo":"agentium-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{},"buildId":"6adbe370139fbc8264ca035a","clientVersion":"0.0.4227","searchFilterCounts":[{"language":"default","tag":"Build","count":129},{"language":"default","tag":"Integrations","count":101},{"language":"default","tag":"Reference","count":87},{"language":"default","tag":"Package APIs","count":66},{"language":"default","tag":"Providers and services","count":61},{"language":"default","tag":"Data and capabilities","count":42},{"language":"default","tag":"@agentium/core","count":39},{"language":"default","tag":"Examples","count":37},{"language":"default","tag":"Toolkits","count":32},{"language":"default","tag":"Ship","count":29}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[],"googleFontsInlined":false},"customCss":[{"filePath":"styles.css","content":".ag-explorer,.ag-directory{--ag-line: #dbe3ee;--ag-muted: #526179;--ag-panel: #f7f9fc;--ag-accent: #1d4ed8;color:#172033}.dark .ag-explorer,.dark .ag-directory{--ag-line: #283448;--ag-muted: #a2afc3;--ag-panel: #111a29;--ag-accent: #93b4ff;color:#e2e8f0}.ag-explorer{border:1px solid var(--ag-line);border-radius:16px;overflow:hidden;margin:24px 0}.ag-explorer button,.ag-directory button,.ag-directory input{font:inherit}.ag-explorer-top,.ag-explorer-bottom,.ag-step-heading{display:flex;justify-content:space-between;align-items:center;gap:12px}.ag-explorer-top{padding:18px 20px 10px}.ag-eyebrow{color:var(--ag-accent);font-size:12px;font-weight:650;letter-spacing:.08em;text-transform:uppercase}.ag-caption,.ag-explorer-bottom,.ag-step-heading span,.ag-directory-count{color:var(--ag-muted);font-size:12px}.ag-scenarios{display:flex;flex-wrap:wrap;gap:8px;padding:8px 20px 18px}.ag-scenarios button,.ag-filters button{padding:6px 12px;border:1px solid var(--ag-line);border-radius:8px;font-size:13px;background:transparent;color:inherit;cursor:pointer}.ag-scenarios button[aria-pressed=\"true\"],.ag-filters button[aria-pressed=\"true\"]{color:var(--ag-accent);border-color:var(--ag-accent);background:var(--ag-panel)}.ag-explorer .ag-step-list{display:flex;flex-wrap:wrap;gap:8px;padding:16px 20px;margin:0;list-style:none;border-top:1px solid var(--ag-line);background:var(--ag-panel)}.ag-step-list li{padding:0;margin:0}.ag-step-list button{display:flex;align-items:center;gap:7px;padding:6px 10px;border-radius:7px;font-size:12px;color:var(--ag-muted);cursor:pointer;background:transparent;border:1px solid transparent}.ag-step-list button[aria-current=\"step\"]{border-color:var(--ag-accent);color:var(--ag-accent)}.ag-step-list button span{font-size:11px;font-weight:600}.ag-step-detail{padding:20px;min-height:214px}.ag-step-detail p{font-size:14px;line-height:1.65;margin:12px 0;color:var(--ag-muted)}.ag-step-detail pre{padding:14px;white-space:pre-wrap;overflow-wrap:anywhere;font-size:12px;line-height:1.7;background:var(--ag-panel);border-radius:8px;margin:0}.ag-explorer-bottom{padding:0 20px 16px}.ag-explorer-bottom button{padding:6px 10px;color:var(--ag-accent);background:transparent;border-radius:6px;cursor:pointer}.ag-explorer-bottom button:disabled{opacity:.4;cursor:default}.ag-explorer .ag-outcome{font-size:12px;line-height:1.7;color:var(--ag-muted);margin:0;padding:14px 20px;border-top:1px solid var(--ag-line)}.ag-directory label{display:block;font-weight:600;margin:20px 0 8px;font-size:14px}.ag-directory input{width:100%;border:1px solid var(--ag-line);border-radius:10px;padding:12px 14px;background:var(--ag-panel);color:inherit;font-size:14px}.ag-filters{display:flex;flex-wrap:wrap;gap:8px;margin:16px 0}.ag-directory-grid{display:grid;grid-template-columns:repeat(2, minmax(0, 1fr));gap:12px;margin:16px 0}.ag-directory .ag-integration{display:block;border:1px solid var(--ag-line);padding:18px;border-radius:10px;text-decoration:none;color:inherit}.ag-integration:hover{border-color:var(--ag-accent);background:var(--ag-panel)}.ag-integration strong{display:block;font-size:15px}.ag-integration small{display:block;color:var(--ag-accent);font-size:11px;margin-bottom:8px}.ag-directory .ag-integration p{color:var(--ag-muted);font-size:13px;line-height:1.6;margin:8px 0 0}.ag-explorer button:focus-visible,.ag-directory button:focus-visible,.ag-directory input:focus-visible,.ag-integration:focus-visible{outline:2px solid var(--ag-accent);outline-offset:3px}@media (max-width: 640px){.ag-directory-grid{grid-template-columns:1fr}.ag-explorer-top,.ag-step-heading{align-items:flex-start;flex-direction:column;gap:4px}.ag-step-detail{min-height:260px}.ag-step-list button{padding:7px}}.ag-explorer .ag-step-detail pre code{width:auto;min-width:0;max-width:100%;white-space:pre-wrap;overflow-wrap:anywhere;word-break:break-word}.ag-explorer .ag-step-detail pre,.ag-explorer .ag-step-detail pre code{color:inherit}"}]}
{"page":{"pagePath":"toolkits/shell","slug":"/toolkits/shell","pageMetadata":{"title":"Shell","description":"Execute shell commands with timeout, output limits, and command allowlisting.","href":"/toolkits/shell"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Execute shell commands with timeout, output limits, and command allowlisting.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,hr:`hr`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,ParamField,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Execute shell commands from your agent. Supports timeouts, output truncation, and an optional command allowlist for safety.`}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`quick-start`,children:`Quick Start`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`16`,language:`typescript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`typescript`,children:_jsxs(_components.code,{language:`typescript`,numberOfLines:`16`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`Agent`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`openai`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` } `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`from`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"@agentium/core\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` { `}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`ShellToolkit`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` } `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`from`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"@agentium/core/toolkits\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`;`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` shell`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` ShellToolkit`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`({`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` timeout:`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#B5CEA8`},children:` 10_000`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` allowedCommands:`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` [`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"ls\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"cat\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"grep\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"find\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"wc\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`],`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`});`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` agent`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:` new`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` Agent`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`({`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` name:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"devops-agent\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` model:`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:` openai`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`process`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`env`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:`OPENAI_MODEL`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` ??`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"gpt-6.1-sol\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`),`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` instructions:`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Help users inspect their system and files.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` tools:`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` [`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`...`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`shell`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`getTools`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`()],`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`});`})}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#569CD6`},children:`const`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#4FC1FF`},children:` result`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` =`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` await`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:` agent`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.`}),_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`run`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"How many TypeScript files are in the src directory?\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`);`})]}),`\n`]})})}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`config`,children:`Config`}),`\n`,_jsx(ParamField,{body:`shell`,type:`string`,id:`param-shell`,children:_jsxs(_components.p,{children:[`Shell to use (default: platform default, e.g. `,_jsx(_components.code,{children:`/bin/sh`}),`).`]})}),`\n`,_jsx(ParamField,{body:`timeout`,type:`number`,default:`30000`,id:`param-timeout`,children:_jsx(_components.p,{children:`Command timeout in milliseconds.`})}),`\n`,_jsx(ParamField,{body:`maxOutput`,type:`number`,default:`10000`,id:`param-max-output`,children:_jsx(_components.p,{children:`Max output characters to return. Long output is truncated from the start.`})}),`\n`,_jsx(ParamField,{body:`cwd`,type:`string`,id:`param-cwd`,children:_jsx(_components.p,{children:`Working directory for commands.`})}),`\n`,_jsx(ParamField,{body:`allowedCommands`,type:`string[]`,id:`param-allowed-commands`,children:_jsx(_components.p,{children:`Allowlist of command prefixes. If set, only commands starting with one of these are permitted.`})}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`tools`,children:`Tools`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Tool`}),_jsx(_components.th,{children:`Description`})]})}),_jsx(_components.tbody,{children:_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`shell_exec`})}),_jsx(_components.td,{children:`Execute a shell command. Returns stdout, stderr, and exit code.`})]})})]}),`\n`,_jsx(_components.hr,{}),`\n`,_jsx(Heading,{level:`2`,id:`security`,children:`Security`}),`\n`,_jsx(_components.p,{children:`The Shell toolkit includes built-in protections against command injection:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Metacharacter rejection`}),`: Commands containing shell metacharacters (`,_jsx(_components.code,{children:`;`}),`, `,_jsx(_components.code,{children:`|`}),`, `,_jsx(_components.code,{children:`\u0026`}),`, `,_jsx(_components.code,{children:\"`\"}),`, `,_jsx(_components.code,{children:`$`}),`, `,_jsx(_components.code,{children:`(`}),`, `,_jsx(_components.code,{children:`)`}),`, `,_jsx(_components.code,{children:`{`}),`, `,_jsx(_components.code,{children:`}`}),`, `,_jsx(_components.code,{children:`\\\\`}),`, `,_jsx(_components.code,{children:`\u003c`}),`, `,_jsx(_components.code,{children:`>`}),`, newlines) are automatically rejected before execution — even if they pass the allowlist check.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:`Allowlist enforcement`}),`: When `,_jsx(_components.code,{children:`allowedCommands`}),` is set, only commands starting with an allowed prefix are permitted.`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`These protections prevent an LLM from chaining commands, piping to other processes, or using shell expansion in arguments.`}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`Always set `,_jsx(_components.code,{children:`allowedCommands`}),` in production to restrict which commands agents can run. Without it, the agent can execute any single command (subject to metacharacter validation).`]})}),`\n`,_jsxs(_components.p,{children:[`See the `,_jsx(_components.a,{href:`/security`,children:`Security`}),` page for a full overview of security hardening across Agentium.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Shell","description":"Execute shell commands with timeout, output limits, and command allowlisting.","href":"/toolkits/shell"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Quick Start","slug":"quick-start","depth":2,"children":[]},{"title":"Config","slug":"config","depth":2,"children":[]},{"title":"Tools","slug":"tools","depth":2,"children":[]},{"title":"Security","slug":"security","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"xhipment","siteName":"Agentium","title":"Shell - Agentium","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-04T16:01:37.387Z","originalFileLocation":"toolkits/shell.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Execute shell commands with timeout, output limits, and command allowlisting.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Agentium\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/xhipment/1FHI9CtiEmrb2QJH/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/xhipment/1FHI9CtiEmrb2QJH/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/xhipment/1FHI9CtiEmrb2QJH/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/xhipment/1FHI9CtiEmrb2QJH/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/xhipment/1FHI9CtiEmrb2QJH/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/xhipment/1FHI9CtiEmrb2QJH/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/xhipment/1FHI9CtiEmrb2QJH/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/xhipment/1FHI9CtiEmrb2QJH/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/xhipment/1FHI9CtiEmrb2QJH/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Shell - Agentium\">\u003cmeta data-mint-head property=\"og:description\" content=\"Execute shell commands with timeout, output limits, and command allowlisting.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Agentium\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.agentium.in/toolkits/shell\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://xhipment.mintlify.site/_mintlify/api/og/v2?division=Toolkits\u0026amp;title=Shell\u0026amp;description=Execute+shell+commands+with+timeout%2C+output+limits%2C+and+command+allowlisting.\u0026amp;theme=df32736373f0bac5d5601052\u0026amp;signature=e1eb409c0b9662c41f5f72aacf22d0dbcaf8ac923587f8f2da39d9dd74d93345\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Shell - Agentium\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Execute shell commands with timeout, output limits, and command allowlisting.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://xhipment.mintlify.site/_mintlify/api/og/v2?division=Toolkits\u0026amp;title=Shell\u0026amp;description=Execute+shell+commands+with+timeout%2C+output+limits%2C+and+command+allowlisting.\u0026amp;theme=df32736373f0bac5d5601052\u0026amp;signature=e1eb409c0b9662c41f5f72aacf22d0dbcaf8ac923587f8f2da39d9dd74d93345\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/xhipment/1FHI9CtiEmrb2QJH/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Agentium\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2563EB\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.agentium.in/toolkits/shell\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/toolkits/shell.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.agentium.in/#organization\",\"name\":\"Agentium\",\"url\":\"https://docs.agentium.in\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/xhipment/Ed5pO8kvbGYPhMpL/logo/light.svg?fit=max\u0026auto=format\u0026n=Ed5pO8kvbGYPhMpL\u0026q=85\u0026s=78e27fa90cb7eeca27547aec06e58eb6\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.agentium.in#website\",\"name\":\"Agentium\",\"url\":\"https://docs.agentium.in\",\"publisher\":{\"@id\":\"https://docs.agentium.in/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.agentium.in/toolkits/shell#webpage\",\"url\":\"https://docs.agentium.in/toolkits/shell\",\"name\":\"Shell\",\"description\":\"Execute shell commands with timeout, output limits, and command allowlisting.\",\"dateModified\":\"2026-10-04T16:01:37.387Z\",\"isPartOf\":{\"@id\":\"https://docs.agentium.in#website\"},\"breadcrumb\":{\"@id\":\"https://docs.agentium.in/toolkits/shell#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.agentium.in/toolkits/shell#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Providers and services\",\"item\":\"https://docs.agentium.in/models/overview\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Toolkits\",\"item\":\"https://docs.agentium.in/toolkits/overview\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Shell\",\"item\":\"https://docs.agentium.in/toolkits/shell\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.agentium.in/toolkits/shell#article\",\"headline\":\"Shell\",\"name\":\"Shell\",\"description\":\"Execute shell commands with timeout, output limits, and command allowlisting.\",\"url\":\"https://docs.agentium.in/toolkits/shell\",\"mainEntityOfPage\":{\"@id\":\"https://docs.agentium.in/toolkits/shell#webpage\"},\"dateModified\":\"2026-10-04T16:01:37.387Z\",\"publisher\":{\"@id\":\"https://docs.agentium.in/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.agentium.in#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Agentium\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Agentium\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/toolkits/shell.md","siteName":"Agentium","nav":{"global":{"anchors":[{"anchor":"GitHub","icon":"github","href":"https://github.com/agentiumOS/agentium"},{"anchor":"npm","icon":"npm","href":"https://www.npmjs.com/org/agentium"}]},"tabs":[{"tab":"Start","pages":[{"title":"Start","href":""}]},{"tab":"Build","pages":[{"title":"Build","href":"/build/overview"}]},{"tab":"Examples","pages":[{"title":"Examples","href":"/examples/overview"}]},{"tab":"Ship","pages":[{"title":"Ship","href":"/ship/overview"}]},{"tab":"Integrations","groups":[{"group":"Find an integration","pages":[{"title":"Connect your stack","sidebarTitle":"Integration directory","mode":"wide","href":"/integrations/overview"}]},{"group":"Voice and call adapters","pages":[{"group":"Speech and media","expanded":false,"pages":[{"title":"OpenAI voice adapters","href":"/voice/openai"},{"title":"ElevenLabs speech adapters","href":"/voice/elevenlabs"},{"title":"Sarvam speech adapters","href":"/voice/sarvam"},{"title":"Google Gemini Live adapter","href":"/voice/google"},{"title":"LiveKit media transport","href":"/voice/livekit"}]},{"group":"Telephony providers","expanded":false,"pages":[{"title":"Twilio call adapter","href":"/telephony/twilio"},{"title":"Telnyx call adapter","href":"/telephony/telnyx"},{"title":"SignalWire call adapter","href":"/telephony/signalwire"},{"title":"Vonage call adapter","href":"/telephony/vonage"},{"title":"Exotel call adapter","href":"/telephony/exotel"},{"title":"LiveKit SIP call adapter","href":"/telephony/livekit"}]}]},{"group":"Sandbox and telemetry","pages":[{"title":"Choose a sandbox backend","href":"/sandbox/overview"},{"title":"Local sandbox backend","href":"/sandbox/local"},{"title":"E2B sandbox adapter","href":"/sandbox/e2b"},{"title":"Daytona sandbox adapter","href":"/sandbox/daytona"},{"title":"Choose a telemetry exporter","href":"/observability/exporters"},{"title":"OpenTelemetry adapters","href":"/observability/opentelemetry"},{"title":"Langfuse OTLP adapter","href":"/observability/langfuse"}]},{"group":"Providers and services","pages":[{"group":"Model providers","expanded":false,"pages":[{"title":"Models","href":"/models/overview"},{"title":"OpenAI","href":"/models/openai"},{"title":"OpenAI Decisions","href":"/models/openai-decisions"},{"title":"Anthropic","href":"/models/anthropic"},{"title":"Google Gemini","href":"/models/google"},{"title":"Vertex AI","href":"/models/vertex"},{"title":"Ollama (Local Models)","href":"/models/ollama"},{"title":"DeepSeek","href":"/models/deepseek"},{"title":"Mistral","href":"/models/mistral"},{"title":"xAI (Grok)","href":"/models/xai"},{"title":"Perplexity","href":"/models/perplexity"},{"title":"Jev (TypeSafe)","href":"/models/jev"},{"title":"Cohere","href":"/models/cohere"},{"title":"Meta (Llama)","href":"/models/meta"},{"title":"Vercel v0","href":"/models/vercel"},{"title":"AWS Bedrock","href":"/models/aws-bedrock"},{"title":"AWS Claude","href":"/models/aws-claude"},{"title":"Azure OpenAI","href":"/models/azure-openai"},{"title":"Azure AI Foundry","href":"/models/azure-foundry"},{"title":"OpenAI-Compatible","href":"/models/openai-like"},{"title":"Implement a model provider","sidebarTitle":"Custom provider","href":"/models/custom-provider"}]},{"group":"Toolkits","expanded":false,"pages":[{"title":"Toolkits","href":"/toolkits/overview"},{"title":"Calculator","href":"/toolkits/calculator"},{"title":"File System","description":"Read, write, list, and inspect local files with path sandboxing.","href":"/toolkits/filesystem"},{"title":"Shell","href":"/toolkits/shell"},{"title":"Wikipedia","description":"Search and read Wikipedia articles — no API key required.","href":"/toolkits/wikipedia"},{"title":"DuckDuckGo","href":"/toolkits/duckduckgo"},{"title":"Hacker News","href":"/toolkits/hackernews"},{"title":"Web Search","href":"/toolkits/websearch"},{"title":"HTTP / REST","href":"/toolkits/http"},{"title":"Web Scraper","href":"/toolkits/scraper"},{"title":"YouTube","href":"/toolkits/youtube"},{"title":"SQL Database","href":"/toolkits/sql"},{"title":"PDF","href":"/toolkits/pdf"},{"title":"Git","href":"/toolkits/git"},{"title":"Code Interpreter","href":"/toolkits/code-interpreter"},{"title":"Google Workspace","href":"/toolkits/google-workspace"},{"title":"Google Sheets","href":"/toolkits/google-sheets"},{"title":"Redis","href":"/toolkits/redis"},{"title":"S3 Cloud Storage","href":"/toolkits/s3"},{"title":"Gmail","href":"/toolkits/gmail"},{"title":"WhatsApp","href":"/toolkits/whatsapp"},{"title":"Slack","href":"/toolkits/slack"},{"title":"Telegram","href":"/toolkits/telegram"},{"title":"Discord","href":"/toolkits/discord"},{"title":"GitHub","href":"/toolkits/github"},{"title":"Jira","href":"/toolkits/jira"},{"title":"Notion","href":"/toolkits/notion"},{"title":"Google Calendar","href":"/toolkits/calendar"},{"title":"Stripe","href":"/toolkits/stripe"},{"title":"Image Generation","href":"/toolkits/image-generation"},{"title":"PageIndex","href":"/toolkits/pageindex"},{"title":"Jev","href":"/toolkits/jev"}]},{"group":"Conversation storage","expanded":false,"pages":[{"title":"Storage Overview","href":"/storage/overview"},{"title":"In-Memory Storage","href":"/storage/in-memory"},{"title":"SQLite Storage","href":"/storage/sqlite"},{"title":"PostgreSQL storage","href":"/storage/postgres"},{"title":"MongoDB Storage","href":"/storage/mongodb"},{"title":"MySQL Storage","href":"/storage/mysql"},{"title":"Redis Storage","href":"/storage/redis"},{"title":"DynamoDB Storage","href":"/storage/dynamodb"}]}]},{"group":"Protocols and devices","pages":[{"group":"MCP","expanded":false,"pages":[{"title":"MCP Client","href":"/mcp/overview"},{"title":"MCP v2 and Tasks","href":"/mcp/v2"},{"title":"MCP Admin API","href":"/mcp/admin"},{"title":"MCP authorization helpers","href":"/mcp/auth-conformance"}]},{"group":"A2A","expanded":false,"pages":[{"title":"A2A Protocol","href":"/a2a/overview"},{"title":"A2A 1.0","href":"/a2a/v1"},{"title":"A2A Server","href":"/a2a/server"},{"title":"A2A Client","href":"/a2a/client"},{"title":"Remote Teams","href":"/a2a/remote-team"},{"title":"Remote Workflows","href":"/a2a/remote-workflow"},{"title":"API Gateway","href":"/a2a/gateway"}]},{"group":"Edge and IoT","expanded":false,"pages":[{"title":"Build a device application","sidebarTitle":"Edge and IoT","href":"/edge/overview"},{"title":"System information","href":"/edge/system"},{"title":"GPIO","href":"/edge/gpio"},{"title":"Servo control","href":"/edge/servo"},{"title":"I2C Sensors","href":"/edge/sensor"},{"title":"Camera","href":"/edge/camera"},{"title":"Bluetooth BLE","href":"/edge/ble"},{"title":"Monitor a device runtime","sidebarTitle":"Edge runtime","href":"/edge/runtime"},{"title":"Ollama on Edge","href":"/edge/ollama-edge"},{"title":"Connect a device to your service","sidebarTitle":"Edge-cloud sync","href":"/edge/edge-cloud"}]}]}]},{"tab":"Reference","pages":[{"title":"Reference","href":"/reference/overview"}]}]},"basePath":"","title":"Shell - Agentium","deploymentId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","buildId":"dpl_vSEmv961Ncyvz1psVwgUnTXQMSYk","dynamics":["10e4515597"],"chunks":["BannerMarkdown-DnSAhvaM.js","dist-DIfYWxfm.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}