A secure shell command execution plugin for ElizaOS that allows agents to run terminal commands within a restricted directory with command history tracking.

Just want your agent to execute commands? Here's the fastest path:

1. Install the plugin:

   cd your-eliza-project
   bun add @elizaos/plugin-shell

2. Create/update your .env:

   SHELL_ENABLED=true
   SHELL_ALLOWED_DIRECTORY=/path/to/safe/directory

3. Add to your character:

   const character = {
       // ... other config
       plugins: ["@elizaos/plugin-shell"],
   };

4. Run: bun start

⚠️ Security note: The agent can ONLY execute commands within SHELL_ALLOWED_DIRECTORY - choose wisely!

• ✅ Cross-platform support: Works on Linux, macOS, and Windows
• ✅ Directory restriction: Commands are restricted to a specified directory for safety
• ✅ Command filtering: Configurable list of forbidden commands
• ✅ Timeout protection: Automatic termination of long-running commands
• ✅ Command history: Tracks command execution history per conversation
• ✅ File operation tracking: Monitors file creation, modification, and deletion
• ✅ Shell context provider: Provides command history and working directory to agent context
• ✅ Output capture: Returns both stdout and stderr from executed commands
• ✅ Safety first: Disabled by default, requires explicit enabling

• Node.js 20+ and bun installed
• ElizaOS project set up
• A designated safe directory for command execution

# Using bun (recommended)
bun add @elizaos/plugin-shell

# Using npm
npm install @elizaos/plugin-shell

# Using pnpm
pnpm add @elizaos/plugin-shell

Create or edit .env file in your project root:

# REQUIRED: Enable the shell plugin (disabled by default for safety)
SHELL_ENABLED=true

# REQUIRED: Set the allowed directory (commands can only run here)
SHELL_ALLOWED_DIRECTORY=/home/user/safe-workspace

# OPTIONAL: Set custom timeout in milliseconds (default: 30000)
SHELL_TIMEOUT=60000

# OPTIONAL: Add additional forbidden commands (comma-separated)
SHELL_FORBIDDEN_COMMANDS=rm,mv,cp,chmod,chown,shutdown,reboot

import { Character } from "@elizaos/core";

const myCharacter: Character = {
    name: "DevAssistant",
    description: "A helpful development assistant",
    plugins: ["@elizaos/plugin-shell"],  // Add the shell plugin
    // ... rest of your character config
};

bun start

Your agent can now execute shell commands! Try:

• "Show me what files are in this directory"
• "Run ls -la"
• "Create a file called hello.txt"
• "Check the git status"

Executes ANY shell command within the allowed directory, including file operations.

Examples:

• run ls -la - List files with details
• execute npm test - Run tests
• show me the current directory - Execute pwd
• create a file called hello.txt - Creates a new file
• write 'Hello World' to output.txt - Write content to file
• make a new directory called src - Create directory
• check git status - Show git repository status

Clears the command history for the current conversation.

Examples:

• clear my shell history
• reset the terminal history
• delete command history

The plugin includes a SHELL_HISTORY provider that makes the following information available to the agent:

• Recent Commands: Last 10 executed commands with their outputs
• Current Working Directory: The current directory within the allowed path
• Allowed Directory: The configured safe directory boundary
• File Operations: Recent file creation, modification, and deletion operations

This context helps the agent understand previous commands and maintain continuity in conversations.

The plugin enforces that ALL commands execute within SHELL_ALLOWED_DIRECTORY:

• Attempts to navigate outside are blocked
• Absolute paths outside the boundary are rejected
• cd .. stops at the allowed directory root

By default, these potentially dangerous commands are blocked:

• Destructive: rm, rmdir
• Permission changes: chmod, chown, chgrp
• System operations: shutdown, reboot, halt, poweroff
• Process control: kill, killall, pkill
• User management: sudo, su, passwd, useradd, userdel
• Disk operations: format, fdisk, mkfs, dd, shred

Note: Safe file operations ARE allowed: touch, echo, cat, mkdir, ls, etc.

• No Shell Expansion: Commands execute without dangerous shell interpretation
• Timeout Protection: Commands auto-terminate after timeout
• Command History: All executed commands are logged for audit
• Path Traversal Protection: Blocks ../ and similar patterns

SHELL_ALLOWED_DIRECTORY=/home/user/projects
SHELL_TIMEOUT=120000  # 2 minutes for build commands

Your agent can help with:

• Running tests and builds
• Git operations
• File management
• Code generation

SHELL_ALLOWED_DIRECTORY=/var/log
SHELL_FORBIDDEN_COMMANDS=rm,mv,cp,chmod,chown  # Read-only access

Your agent can:

• Check log files
• Monitor system status
• Generate reports

SHELL_ALLOWED_DIRECTORY=/home/user/content

Your agent can:

• Create and organize files
• Process text files
• Manage content structure

Checklist:

• ✅ Is SHELL_ENABLED=true in your .env?
• ✅ Does SHELL_ALLOWED_DIRECTORY exist and is accessible?
• ✅ Is the plugin added to your character's plugins array?
• ✅ Check logs for "Shell service initialized"

Solution: Set SHELL_ENABLED=true in your .env file

This is a security feature! The agent cannot access files outside SHELL_ALLOWED_DIRECTORY.

Solution:

• Move your work to the allowed directory, OR
• Change SHELL_ALLOWED_DIRECTORY to include your work area

The command you're trying to run is in the forbidden list.

Solution:

• Use alternative safe commands, OR
• Remove the command from SHELL_FORBIDDEN_COMMANDS if you trust your environment

The command might not be in the system PATH.

Solution:

• Use full paths: /usr/bin/git instead of git
• Ensure required tools are installed

Each conversation maintains its own:

• Command history (last 100 commands)
• Working directory context
• File operation tracking

This ensures privacy between different users/conversations.

# For development environments with slow builds
SHELL_TIMEOUT=300000  # 5 minutes

# For trusted environments
SHELL_FORBIDDEN_COMMANDS=shutdown,reboot

# Block all write operations
SHELL_FORBIDDEN_COMMANDS=rm,rmdir,mv,cp,touch,mkdir,echo,cat,chmod,chown,dd

# Clone the repository
git clone https://github.com/elizaos/eliza.git
cd eliza/packages/plugin-shell

# Install dependencies
bun install

# Build the plugin
bun run build

# Run tests
bun test

# Run with debug logging
DEBUG=eliza:* bun start

1. Test Basic Commands: Try ls, pwd, echo test
2. Test Restrictions: Try cd / (should fail)
3. Test History: Run commands then ask "what commands have I run?"
4. Test File Ops: Create a file, then check history for tracking

┌─────────────────┐     ┌──────────────────┐     ┌────────────────┐
│   Your Agent    │────▶│  Shell Plugin    │────▶│  cross-spawn   │
│                 │     │                  │     │                │
│  "run ls -la"   │     │ - Path validation│     │ - Secure exec  │
│                 │     │ - History track  │     │ - No shell     │
└─────────────────┘     │ - Timeout mgmt   │     └────────────────┘
                        └──────────────────┘

1. Agent receives command request
2. Plugin validates command safety
3. Checks directory boundaries
4. Executes via cross-spawn (no shell)
5. Captures output and errors
6. Tracks in conversation history
7. Returns formatted result

Contributions are welcome! Please:

1. Check existing issues first
2. Follow the code style
3. Add tests for new features
4. Update documentation

# Run all tests
bun test

# Run specific test file
bun test src/__tests__/shellHistory.test.ts

# Run tests in watch mode
bun test --watch

• ElizaOS Documentation
• Security Best Practices
• Cross-spawn Documentation

This plugin is part of the ElizaOS project. See the main repository for license information.