Skip to main content
Sandbox provides secure, isolated environments for executing code generated by AI agents, protecting your system from potentially harmful operations.

​
Quick Start

1

Configure Sandbox

from praisonaiagents import SandboxConfig, ResourceLimits

config = SandboxConfig(
    sandbox_type="subprocess",
    resource_limits=ResourceLimits(
        memory_mb=256,
        timeout_seconds=30
    )
)
2

Execute Code via CLI

# Run Python code
praisonai sandbox run "print('Hello, World!')"

# Run with timeout
praisonai sandbox run --timeout 10 "import time; time.sleep(5)"
3

Check Result

from praisonaiagents import SandboxResult, SandboxStatus

# Result contains status, output, and errors
if result.status == SandboxStatus.COMPLETED:
    print(result.stdout)
else:
    print(f"Error: {result.error}")

​
How It Works

ComponentRole
SandboxManages isolation and resource limits
ContainerIsolated execution environment
ResourceLimitsCPU, memory, and time constraints
SecurityPolicyFile and network access rules

​
Sandbox Types

Lightweight isolation using OS-level restrictions.
from praisonaiagents import SandboxConfig

config = SandboxConfig.subprocess()
Best for: Quick execution, development, trusted code

​
Configuration Options

from praisonaiagents import SandboxConfig, ResourceLimits, SecurityPolicy

config = SandboxConfig(
    sandbox_type="docker",
    image="python:3.11-slim",
    working_dir="/workspace",
    resource_limits=ResourceLimits(
        memory_mb=512,
        cpu_percent=50,
        timeout_seconds=60,
        network_enabled=False
    ),
    security_policy=SecurityPolicy(
        allow_network=False,
        allow_file_write=True,
        allow_subprocess=False
    ),
    auto_cleanup=True
)
OptionTypeDefaultDescription
sandbox_typestr"subprocess"Type: subprocess, docker, e2b
imagestr"python:3.11-slim"Docker image
working_dirstr"/workspace"Working directory
auto_cleanupboolTrueAuto-cleanup after execution
persist_filesboolFalseKeep files between runs

​
Resource Limits

Control resource usage to prevent abuse: 
from praisonaiagents import ResourceLimits

# Minimal limits for untrusted code
limits = ResourceLimits.minimal()  # 128MB, 30s, no network

# Standard limits
limits = ResourceLimits.standard()  # 512MB, 60s

# Generous limits for trusted code
limits = ResourceLimits.generous()  # 2GB, 300s, network allowed
LimitMinimalStandardGenerous
memory_mb1285122048
timeout_seconds3060300
cpu_percent50100100
network_enabled❌❌✅

​
Security Policy

Fine-grained security controls: 
from praisonaiagents import SecurityPolicy

# Strict policy
policy = SecurityPolicy.strict()

# Standard policy
policy = SecurityPolicy.standard()

# Permissive policy (trusted code only)
policy = SecurityPolicy.permissive()

# Custom policy
policy = SecurityPolicy(
    allow_network=False,
    allow_file_write=True,
    allow_subprocess=False,
    blocked_paths=["/etc", "~/.ssh"],
    blocked_imports=["subprocess", "os.system"]
)

​
Result Handling

from praisonaiagents import SandboxResult, SandboxStatus

result = await sandbox.execute("print('Hello')")

# Check status
if result.status == SandboxStatus.COMPLETED:
    print(f"Output: {result.stdout}")
elif result.status == SandboxStatus.TIMEOUT:
    print("Execution timed out")
elif result.status == SandboxStatus.FAILED:
    print(f"Error: {result.stderr}")
elif result.status == SandboxStatus.KILLED:
    print("Process was killed (resource limit)")

# Access details
print(f"Exit code: {result.exit_code}")
print(f"Duration: {result.duration_seconds}s")

​
CLI Commands

# Run code
praisonai sandbox run "print('Hello')"

# Run with file
praisonai sandbox run --file script.py

# Interactive shell
praisonai sandbox shell

# With resource limits
praisonai sandbox run --memory 256 --timeout 30 "code"

# Using Docker
praisonai sandbox run --type docker --image python:3.11 "code"

# Check status
praisonai sandbox status

​
Common Patterns

from praisonaiagents import Agent, SandboxConfig

agent = Agent(
    name="coder",
    instructions="Write and execute Python code",
    sandbox=SandboxConfig(
        sandbox_type="docker",
        resource_limits=ResourceLimits.standard()
    )
)

​
Best Practices

Always use Docker sandbox when executing code from untrusted sources. Subprocess isolation is not sufficient for security-critical applications.
Configure memory and timeout limits based on expected workload. Start with minimal limits and increase as needed.
Keep network_enabled=False unless the code specifically needs network access. This prevents data exfiltration.
Customize blocked_paths and blocked_imports in SecurityPolicy to prevent access to sensitive system resources.

Code Agent

AI-powered code generation

Tools

Extend agent capabilities