Sandbox Backends

Execute commands safely with configurable shell control across different backends

Sandbox backends provide isolated command execution environments with explicit shell control to prevent injection attacks while enabling shell features when needed.

Quick Start

1. Safe Command Execution

   Execute commands safely without shell features:

   from praisonaiagents import Agent
   from praisonai.sandbox import SubprocessSandbox
   
   # Create agent with safe command execution
   agent = Agent(
       name="System Agent",
       instructions="Execute system commands safely",
   )
   
   # Create sandbox for safe execution
   sandbox = SubprocessSandbox()
   
   # Execute without shell (default, safe)
   result = await sandbox.run_command("ls -la")
   print(result.stdout)
   
2. With Shell Features

   Enable shell features when needed:

   from praisonaiagents import Agent
   from praisonai.sandbox import DockerSandbox
   
   agent = Agent(
       name="Data Agent", 
       instructions="Process data with shell pipelines"
   )
   
   sandbox = DockerSandbox()
   
   # Execute with shell features (explicit opt-in)
   result = await sandbox.run_command(
       "cat data.txt | grep 'error' | wc -l",
       shell=True
   )
   print(f"Error count: {result.stdout.strip()}")
   

---

How It Works

Backend	Use Case	Security Level
SubprocessSandbox	Local development, scripts	Medium (OS-level isolation)
DockerSandbox	Production, untrusted code	High (container isolation)
SSHSandbox	Remote execution	High (network isolation)

---

Configuration Options

Shell Parameter Control

shell=False (Default)

# String commands are parsed safely
result = await sandbox.run_command("python script.py --arg value")

# List commands are executed directly
result = await sandbox.run_command(["python", "script.py", "--arg", "value"])

Security: No shell injection possible. String commands are parsed with shlex.split().

shell=True (Opt-in)

# Shell features available: pipes, redirects, globs
result = await sandbox.run_command(
    "find . -name '*.py' | xargs grep 'TODO' > todos.txt",
    shell=True
)

# Environment variable expansion
result = await sandbox.run_command(
    "echo $HOME && ls $PWD/*.log", 
    shell=True
)

Security: Shell evaluation enabled. Only use with trusted input.

Set shell=True only when you need shell features (pipes, &&, globbing). With untrusted input always keep shell=False.

Decision Guide

Use Case	Recommended shell Value
Running a single executable with arguments	False
Pipelines (grep | sort)	True
Globs and env-var expansion	True
Untrusted / model-generated commands	False

---

Common Patterns

Backend Selection

Development

from praisonai.sandbox import SubprocessSandbox

# Local development with subprocess
sandbox = SubprocessSandbox()
result = await sandbox.run_command("python test.py")

Production

from praisonai.sandbox import DockerSandbox

# Isolated container execution
sandbox = DockerSandbox(
    image="python:3.11-slim",
    timeout=30
)
result = await sandbox.run_command("python app.py", shell=False)

Remote

from praisonai.sandbox import SSHSandbox

# Remote server execution
sandbox = SSHSandbox(
    host="remote.server.com",
    username="runner"
)
result = await sandbox.run_command(["python", "remote_task.py"])

Safe Data Processing

from praisonai.sandbox import DockerSandbox

sandbox = DockerSandbox()

# Process user data safely
async def process_file(filename):
    # Safe: no shell injection possible
    result = await sandbox.run_command([
        "python", "process.py", "--input", filename
    ], shell=False)
    return result.stdout

# Process with shell features when controlled
async def count_errors(log_file):
    import shlex
    # Trusted input, need shell features  
    result = await sandbox.run_command(
        f"grep 'ERROR' {shlex.quote(log_file)} | wc -l",
        shell=True
    )
    return int(result.stdout.strip())

Resource Limits

from praisonai.sandbox import ResourceLimits, SubprocessSandbox

limits = ResourceLimits(
    timeout_seconds=30,
    memory_mb=512
)

sandbox = SubprocessSandbox()
result = await sandbox.run_command(
    "python heavy_task.py",
    limits=limits,
    shell=False
)

---

Best Practices

Always use shell=False for untrusted input

Model-generated commands or user input should never use shell=True to prevent injection attacks. The default shell=False provides automatic protection.

# ✅ Safe with any user input
user_script = request.get("script")
result = await sandbox.run_command(f"python {user_script}", shell=False)

# ❌ Vulnerable to injection
result = await sandbox.run_command(f"python {user_script}", shell=True)

Quote arguments when building shell commands

If you must use shell=True, quote all dynamic arguments with shlex.quote():

import shlex

filename = user_input  # Could contain special characters
command = f"process.py --file {shlex.quote(filename)}"
result = await sandbox.run_command(command, shell=True)

Prefer list form for complex commands

Using argument lists avoids shell parsing entirely:

# ✅ Clear and injection-safe
result = await sandbox.run_command([
    "python", "script.py", 
    "--input", input_file,
    "--output", output_file
], shell=False)

# ❌ Requires careful quoting
import shlex
command = f"python script.py --input {shlex.quote(input_file)} --output {shlex.quote(output_file)}"
result = await sandbox.run_command(command, shell=True)

Use appropriate backend for your security needs

Choose the sandbox backend based on your isolation requirements:

• Development: SubprocessSandbox for speed and convenience
• Production: DockerSandbox for container-level isolation
• Remote: SSHSandbox for network-isolated execution
• High Security: Always use Docker or SSH backends with shell=False

---

Related

Resource Limits

Configure timeouts and memory limits for sandbox execution

Thread Safety

Understanding thread-safe operations across PraisonAI components