Shell Execution

The shell-exec skill lets agents run shell commands on the host machine. It is the most powerful built-in skill and requires careful configuration.

Configuration

Configure shell execution behavior per-agent in the config file. The shellExec block controls sandboxing, timeouts, and command restrictions.

json

{
  "name": "Atlas",
  "skills": ["shell-exec"],
  "shellExec": {
    "shell": "/bin/bash",
    "cwd": "./workspace",
    "timeout": 30000,
    "maxOutputSize": "1MB",
    "allowlist": ["git *", "npm *", "node *", "ls *", "cat *"],
    "denylist": ["rm -rf /", "sudo *", "chmod 777 *"],
    "env": {
      "NODE_ENV": "development"
    }
  }
}

Command filtering

Use allowlists and denylists to control which commands the agent can execute. Patterns support glob matching.

Option	Behavior	Default
allowlist	Only matching commands are permitted. If empty, all commands are allowed (unless denied).	[]
denylist	Matching commands are blocked, even if they pass the allowlist.	["rm -rf /", "sudo *"]
confirmDangerous	Prompt the user before executing commands matching dangerous patterns.	true

Without an allowlist, agents can run any command not in the denylist. For production deployments, always define an explicit allowlist of permitted commands.

Output handling

Command output (stdout and stderr) is captured and returned to the agent. Large outputs are automatically truncated to stay within the maxOutputSize limit.

typescript

// What the agent receives from shell-exec
interface ShellResult {
  exitCode: number
  stdout: string
  stderr: string
  truncated: boolean
  durationMs: number
}

If a command times out, the process is killed and the agent receives a partial output with exitCode: -1 and a timeout message in stderr.

← Custom Skills Channels →