Sandbox Execution

Secure isolated execution environment for AI-generated commands

​

Sandbox Execution

PraisonAI CLI provides sandboxed execution for running AI-generated commands safely. Inspired by Codex CLI’s sandbox modes, this feature isolates command execution with configurable security policies.

No CLI flag routes agent commands through this executor. The legacy praisonai "…" --sandbox off|basic|strict flag is display-only and prints: “--sandbox is not enforced here; commands run uncontained. Use praisonai code with PRAISON_SHELL=sandboxed for OS-level containment.” The modes below apply only when you call SandboxExecutorHandler from Python.

The praisonai code coding agent has its own OS-level containment for every shell command — Seatbelt (macOS) or bwrap (Linux), driven by PRAISON_SHELL=sandboxed. It is the path that actually runs on macOS today, distinct from SandboxConfig.native() (Linux-only sandlock). See OS Sandbox.

​

Overview

The sandbox provides:

• Command validation - Block dangerous commands
• Resource limits - CPU, memory, and time limits
• Path restrictions - Control filesystem access
• Network isolation - Optional network blocking
• Execution isolation - Separate working directory

​

Quick Start

# Real OS-level containment for the coding agent
PRAISON_SHELL=sandboxed praisonai code

# Policy-based executor from Python
from praisonai.cli.features import SandboxExecutorHandler

handler = SandboxExecutorHandler()
handler.initialize(mode="basic")
print(handler.execute("echo hello").stdout)

​

Sandbox Modes

​

Disabled (Default)

No sandboxing. Commands run normally.

​

Basic

Light sandboxing with resource limits:

handler.initialize(mode="basic")

Restrictions:

• ✅ 512MB memory limit
• ✅ 60 second timeout
• ✅ Blocked dangerous commands (rm -rf, sudo, etc.)
• ✅ Network access allowed

​

Strict

Heavy sandboxing with filesystem isolation:

handler.initialize(mode="strict")

Restrictions:

• ✅ 256MB memory limit
• ✅ 30 second timeout
• ✅ Blocked dangerous commands
• ✅ Blocked network tools (curl, wget, etc.)
• ✅ Isolated temporary directory
• ✅ Limited process count (5)

​

Network Isolated

No network access:

handler.initialize(mode="network_isolated")

Restrictions:

• ✅ 512MB memory limit
• ✅ 60 second timeout
• ✅ Blocked dangerous commands
• ❌ No network access

​

Python API

​

Basic Usage

from praisonai.cli.features import SandboxExecutorHandler

# Initialize with a mode
handler = SandboxExecutorHandler()
sandbox = handler.initialize(mode="basic")

# Execute a command
result = handler.execute("echo 'Hello, World!'")

print(f"Success: {result.success}")
print(f"Output: {result.stdout}")
print(f"Was sandboxed: {result.was_sandboxed}")

​

Execution Result

result = handler.execute("ls -la")

# Result properties
print(f"Success: {result.success}")
print(f"Exit code: {result.exit_code}")
print(f"Stdout: {result.stdout}")
print(f"Stderr: {result.stderr}")
print(f"Duration: {result.duration_ms}ms")
print(f"Sandboxed: {result.was_sandboxed}")
print(f"Violations: {result.policy_violations}")

​

Command Validation

# Validate before executing
violations = handler.validate_command("rm -rf /")

if violations:
    print("Command blocked:")
    for v in violations:
        print(f"  - {v}")
else:
    result = handler.execute("rm -rf /")

​

Custom Policy

from praisonai.cli.features.sandbox_executor import (
    SandboxPolicy,
    SandboxMode,
    SubprocessSandbox
)

# Create custom policy
policy = SandboxPolicy(
    mode=SandboxMode.BASIC,
    max_memory_mb=1024,
    max_cpu_seconds=120,
    max_file_size_mb=50,
    max_processes=20,
    allow_network=True,
    blocked_commands={"rm", "sudo", "chmod"},
    blocked_paths={"/etc", "/var", "/usr"}
)

# Use custom policy
sandbox = SubprocessSandbox(policy=policy)
result = sandbox.execute("my_command")

​

Blocked Commands

By default, these commands are blocked:

Command	Reason
rm	File deletion
rmdir	Directory deletion
mv	File moving (can overwrite)
dd	Disk operations
mkfs	Filesystem creation
fdisk	Disk partitioning
sudo	Privilege escalation
su	User switching
chmod	Permission changes
chown	Ownership changes
kill	Process termination
pkill	Process termination

​

Strict Mode Additional Blocks

Command	Reason
curl	Network access
wget	Network access
nc / netcat	Network access
ssh	Remote access
scp	Remote file transfer

​

Dangerous Patterns

These patterns are always blocked:

# Recursive force delete
"rm -rf /"  # Blocked

# Device file access
"> /dev/sda"  # Blocked

# Shell piping
"cat file | sh"  # Blocked
"cat file | bash"  # Blocked

# Command substitution
"$(dangerous_command)"  # Blocked
"`dangerous_command`"  # Blocked

​

Path Restrictions

​

Blocked Paths (Strict Mode)

blocked_paths = {
    "/etc",      # System configuration
    "/var",      # Variable data
    "/usr",      # User programs
    "/bin",      # Essential binaries
    "/sbin",     # System binaries
    "/root",     # Root home
    "/home",     # User homes
    "/sys",      # Kernel interface
    "/proc"      # Process information
}

​

Allowed Paths

# Configure allowed paths
policy = SandboxPolicy(
    mode=SandboxMode.STRICT,
    allowed_paths={
        "/tmp",
        "/path/to/project",
        "/path/to/data"
    }
)

​

Resource Limits

​

Memory Limit

policy = SandboxPolicy(
    max_memory_mb=256  # 256MB limit
)

​

CPU Time Limit

policy = SandboxPolicy(
    max_cpu_seconds=30  # 30 second timeout
)

​

Process Limit

policy = SandboxPolicy(
    max_processes=5  # Max 5 child processes
)

​

Integration with Autonomy Modes

Sandbox works with autonomy modes:

from praisonai.cli.features import (
    SandboxExecutorHandler,
    AutonomyModeHandler
)

# Set up autonomy
autonomy = AutonomyModeHandler()
autonomy.initialize(mode="auto_edit")

# Set up sandbox
sandbox = SandboxExecutorHandler()
sandbox.initialize(mode="basic")

# Commands go through both:
# 1. Autonomy check (approval if needed)
# 2. Sandbox validation
# 3. Sandboxed execution

​

Error Handling

​

Timeout

result = sandbox.execute("sleep 100", timeout=5)

if not result.success:
    if "timed out" in result.stderr.lower():
        print("Command timed out")

​

Policy Violation

result = sandbox.execute("rm -rf /")

if result.policy_violations:
    print("Command blocked by policy:")
    for violation in result.policy_violations:
        print(f"  - {violation}")

​

Execution Error

result = sandbox.execute("nonexistent_command")

if not result.success:
    print(f"Error: {result.stderr}")
    print(f"Exit code: {result.exit_code}")

​

Best Practices

​

When to Use Sandbox

Scenario	Recommended Mode
Running user-provided code	strict
AI-generated shell commands	basic
Processing untrusted data	strict
Local file operations	basic
Network-sensitive tasks	network-isolated
Trusted automation	disabled

​

Security Tips

1. Start with strict - Relax restrictions as needed
2. Review violations - Check what’s being blocked
3. Use network isolation - When network isn’t needed
4. Set timeouts - Prevent runaway processes
5. Limit resources - Prevent resource exhaustion

​

Environment Variables

# Default sandbox mode
export PRAISONAI_SANDBOX_MODE=basic

# Disable sandbox entirely (not recommended)
export PRAISONAI_DISABLE_SANDBOX=false

# Custom timeout
export PRAISONAI_SANDBOX_TIMEOUT=60

​

CLI Flags

The legacy --sandbox off|basic|strict flag only prints a not-enforced warning; it does not use this executor. For containment from the CLI:

PRAISON_SHELL=sandboxed praisonai code

​

Troubleshooting

​

Command Unexpectedly Blocked

# Check what's being blocked
violations = handler.validate_command("my_command")
print(violations)

# Adjust policy if needed
policy = SandboxPolicy(
    mode=SandboxMode.BASIC,
    blocked_commands={"rm", "sudo"}  # Reduced list
)

​

Timeout Too Short

# Increase timeout
result = handler.execute("long_running_command", timeout=300)

# Or in policy
policy = SandboxPolicy(max_cpu_seconds=300)

​

Path Access Denied

# Add to allowed paths
policy = SandboxPolicy(
    allowed_paths={"/path/to/needed/directory"}
)

​

Related Features

• Autonomy Modes - Control AI autonomy
• Git Integration - Safe code changes
• Slash Commands - Interactive commands