packages/docs/plugin-registry/shell.md
The Shell plugin gives Eliza agents direct access to the system shell, allowing them to execute arbitrary commands. USE AT YOUR OWN RISK. THIS GIVES AI FULL ACCESS TO THE SYSTEM SHELL.
Package: @elizaos/plugin-shell (core plugin — always loaded)
This plugin exposes shell command execution to agents, enabling them to run system commands, scripts, and tools directly. It includes a configurable security model with command whitelists, blacklists, timeouts, and output size limits. Despite these controls, granting shell access to an AI agent carries inherent risk and should be configured carefully.
This plugin is a core plugin and is always loaded. No manual installation is required.
The plugin auto-enables when the SHELL_ALLOWED_COMMANDS environment variable is set, defining which commands the agent is permitted to run.
| Parameter | Type | Required | Description |
|---|---|---|---|
SHELL_ALLOWED_COMMANDS | string | No | Comma-separated whitelist of allowed commands |
SHELL_TIMEOUT_MS | string | No | Maximum execution time in milliseconds |
SHELL_MAX_OUTPUT_SIZE | string | No | Maximum output size in bytes |
SHELL_WORKING_DIR | string | No | Default working directory |
SHELL_ENABLE_DANGEROUS | boolean | No | Enable dangerous commands (rm -rf, etc.) |
SHELL_LOG_COMMANDS | boolean | No | Log all executed commands |
SHELL_BLOCKED_COMMANDS | string | No | Comma-separated blacklist of blocked commands |
Example configuration via environment variables:
export SHELL_ALLOWED_COMMANDS="ls,cat,grep,find,git"
export SHELL_TIMEOUT_MS="10000"
export SHELL_MAX_OUTPUT_SIZE="1048576"
export SHELL_WORKING_DIR="/home/user/project"
export SHELL_LOG_COMMANDS=true
SHELL_ALLOWED_COMMANDS to restrict the agent to a known-safe set of commands rather than relying solely on SHELL_BLOCKED_COMMANDS.SHELL_ENABLE_DANGEROUS in production. This flag permits destructive commands like rm -rf.SHELL_LOG_COMMANDS=true) for auditability.