Skip to main content

​
Shell

Execute shell commands from your agent. Supports timeouts, output truncation, and an optional command allowlist for safety.

​
Quick Start

import { Agent, openai, ShellToolkit } from "@radaros/core";

const shell = new ShellToolkit({
  timeout: 10_000,
  allowedCommands: ["ls", "cat", "grep", "find", "wc"],
});

const agent = new Agent({
  name: "devops-agent",
  model: openai("gpt-4o"),
  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

​
shell
string
Shell to use (default: platform default, e.g. /bin/sh).
​
timeout
number
default:"30000"
Command timeout in milliseconds.
​
maxOutput
number
default:"10000"
Max output characters to return. Long output is truncated from the start.
​
cwd
string
Working directory for commands.
​
allowedCommands
string[]
Allowlist of command prefixes. If set, only commands starting with one of these are permitted.

​
Tools

ToolDescription
shell_execExecute 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 RadarOS.