Shell Commands

Iris can execute shell commands on your server, enabling file operations, system queries, running scripts, and other CLI tasks. This turns Iris into a capable assistant for development workflows and system administration.

WARNING

Shell command execution is disabled by default. Enable it only on trusted deployments where you understand the security implications.

What You Can Do

With shell commands enabled, Iris can help with:

• File operations: Reading, writing, listing, moving files
• Running scripts: Build tools, test suites, deployment scripts
• System diagnostics: Disk usage, process monitoring, logs
• Development tasks: Git operations, package management, database queries
• Project management: Creating directories, scaffolding, file organization

Setup

Enable shell commands in your .env:

IRIS_SHELL_ENABLED=true

That's it - Iris can now execute commands during conversations.

Example Conversations

File Operations

You: "What's in my Downloads folder?"

Iris: [executes ls -la ~/Downloads]

"You have 23 files in Downloads. The largest ones are: project-backup.zip (2.1GB), video-recording.mp4 (890MB)..."

Git Workflow

You: "What's the git status of my project at ~/code/myapp?"

Iris: [executes git status in that directory]

"You have 3 modified files and 1 untracked file. The modified files are: app/Models/User.php, config/app.php, and routes/web.php. Want me to show you the diff?"

Running Commands

You: "Run the test suite for my Laravel project"

Iris: [executes php artisan test]

"All 47 tests passed. 2 tests were skipped (marked as incomplete). The suite took 4.2 seconds."

Multi-Step Tasks

You: "Create a project structure with src, tests, and config directories, then initialize git"

Iris: [executes multiple commands]

"Done! I created the directories and initialized a git repo. Here's what I did:

• Created project/src, project/tests, project/config
• Ran git init
• The repo is ready for your first commit."

How Iris Handles Errors

Iris doesn't give up when something fails. It reads the error, diagnoses the issue, and tries to fix it:

You: "Install the spatie/laravel-permission package"

Iris: [runs composer require spatie/laravel-permission]

[command fails - PHP version mismatch]

Iris: "The latest version requires PHP 8.2, but you're on 8.1. Let me install a compatible version..."

[runs composer require spatie/laravel-permission:^5.0]

"Installed spatie/laravel-permission v5.11. This version is compatible with your PHP 8.1 setup."

Security

Shell commands include multiple safety layers to prevent dangerous operations.

Blocked Commands

Privilege escalation tools are always blocked:

• sudo, su, doas, pkexec

Attempting these returns an error explaining why.

Blocked Patterns

Dangerous command patterns are detected and rejected:

• Recursive force deletion of root (rm -rf /)
• Direct writes to disk devices (> /dev/sda)
• Filesystem formatting (mkfs)
• Raw disk writes (dd of=/dev/...)

Clean Environment

Commands run with only essential environment variables:

Variable	Purpose
PATH	System path
HOME	User home directory
USER	Current user
SHELL	User's shell
TERM	Terminal type
LANG, LC_ALL	Locale settings

Sensitive variables (API keys, tokens, credentials) are not inherited.

Resource Limits

• Timeout: Commands timeout after the specified duration (default 30s, max 300s)
• Output size: Controlled by shell.max_output_length (default 50,000 characters). When output exceeds this limit, Iris shows the tail of the output — the last N characters — because shell command endings typically contain the most relevant information: error messages, final results, exit summaries. The beginning of long output (verbose startup logs, progress bars) is less useful to the model.

When truncation occurs, a notice is prepended to the output:

... [OUTPUT TRUNCATED — showing last 50000 of 120000 characters]

The full output is preserved in the database; truncation only affects what's sent to the LLM's context window.

Configuration

Customize shell behavior in config/iris.php:

'shell' => [
    'enabled' => env('IRIS_SHELL_ENABLED', false),
    'default_timeout' => 30,
    'max_timeout' => 300,
    'max_output_length' => 50000,
    'default_working_directory' => null,
    'blocked_executables' => ['sudo', 'su', 'doas', 'pkexec'],
    'blocked_patterns' => [
        // Dangerous patterns...
    ],
    'inherit_env_vars' => ['PATH', 'HOME', 'USER', 'SHELL', 'TERM', 'LANG', 'LC_ALL'],
],

Setting a Default Directory

If most of your work happens in one place:

// config/iris-custom.php
return [
    'shell' => [
        'default_working_directory' => '/home/user/projects',
    ],
];

Adding More Blocked Commands

Block additional executables you don't want Iris to use:

// config/iris-custom.php
return [
    'shell' => [
        'blocked_executables' => [
            'sudo', 'su', 'doas', 'pkexec',  // Keep the defaults
            'shutdown', 'reboot', 'halt',     // Add more
        ],
    ],
];

Tips for Effective Use

Be specific about locations: "List files in /var/log" works better than "show me log files"

Include project context: "In my Rails project at ~/code/myapp, run the test suite"

Let Iris iterate: If something fails, Iris will try alternative approaches before asking for help

Verify critical operations: For important file changes, ask Iris to show you what changed

When Iris Asks for Help

Most errors are handled autonomously, but some require your input:

Genuine blockers:

• Ambiguous requirements ("Which config format?")
• Destructive operations without explicit permission
• Missing credentials or authentication
• Fundamental approach decisions

Not blockers (Iris handles these):

• Command syntax errors
• Missing dependencies
• Wrong file paths
• Permission issues with workarounds

Troubleshooting

Command blocked: If a command is blocked, Iris will explain why. You may need to run it manually outside of Iris.

Timeout errors: For long-running commands, ask Iris to increase the timeout: "Run the full test suite with a 5 minute timeout"

Permission denied: Iris can't use sudo. If elevated permissions are needed, you'll need to run that command yourself.

Output truncated: When output exceeds shell.max_output_length (default 50,000 characters), Iris shows the tail of the output. The truncation notice at the top of the response tells you how many characters were omitted. Ask Iris to filter or summarize if you need specific information from earlier in the output.

Disabling Shell Commands

To disable (the default), ensure your .env doesn't enable it:

# .env
IRIS_SHELL_ENABLED=false

Or disable the tool while keeping other tools:

// config/iris-custom.php
return [
    'disabled_tools' => [
        App\Tools\Shell\RunShellCommandTool::class,
    ],
];