Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

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