Sandbox - PraisonAI

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

Quick Start

Simple Usage

Enable sandbox with a single line - the easiest way to get started.

from praisonaiagents import Agent

agent = Agent(
    name="Coder",
    instructions="Write and execute Python code safely.",
    sandbox=True  # one-line enable
)

agent.start("Calculate fibonacci(10) and print the result")

With Configuration

Use factory methods for specific sandbox types.

from praisonaiagents import Agent, SandboxConfig

agent = Agent(
    name="DataAnalyst",
    instructions="Analyze data with Python.",
    sandbox=SandboxConfig.docker("python:3.11-slim")
)

agent.start("Read CSV data and create a summary")

Full Configuration

Complete control over sandbox settings.

from praisonaiagents import Agent, SandboxConfig, ResourceLimits, SecurityPolicy

agent = Agent(
    name="SecureAgent",
    instructions="Execute code with strict security.",
    sandbox=SandboxConfig(
        sandbox_type="e2b",
        resource_limits=ResourceLimits(memory_mb=512, timeout_seconds=60),
        security_policy=SecurityPolicy.standard(),
    )
)

agent.start("Process sensitive data securely")

Agent Sandbox API

When sandbox is configured, agents gain powerful execution capabilities:

import asyncio
from praisonaiagents import Agent

agent = Agent(
    name="DataAnalyst",
    instructions="Analyze data with Python.",
    sandbox=True,
)

# Async pattern
async def main():
    result = await agent.execute_code("""
import statistics
data = [1, 2, 3, 4, 5, 100]
print(f"Mean: {statistics.mean(data)}")
print(f"Median: {statistics.median(data)}")
""")
    print(result.stdout)
    print(f"Status: {result.status}, Exit: {result.exit_code}")

asyncio.run(main())

# Sync pattern (for non-async code)
result = agent.execute_code_sync("print(2 + 2)")
print(result.stdout)

SandboxMixin API

Method	Signature	Description
`has_sandbox`	`property -> bool`	Whether sandbox is configured
`execute_code`	`async (code, language="python", check_security=True, **kwargs) -> SandboxResult`	Async code execution with optional security pre-check
`execute_code_sync`	`(code, language="python", check_security=True, **kwargs) -> SandboxResult`	Sync wrapper around `execute_code`
`run_shell_command`	`async (command: str \| list, check_security=True, **kwargs) -> SandboxResult`	Run shell command in sandbox
`get_sandbox_status`	`() -> Dict[str, Any]`	Returns `{"configured", "config", "available_types", "current_type"}`
`sandbox_cleanup`	`async () -> None`	Force cleanup of sandbox resources
`get_sandbox_manager`	`() -> SandboxManager \| None`	Get or lazily create the manager

Auto-Generated Agent Tools

When sandbox is set on an Agent, two tools are automatically available:

from praisonaiagents import Agent

agent = Agent(
    name="ShellAgent",
    instructions="Use execute_python_code or execute_shell_command to answer questions.",
    sandbox=True,
)

agent.start("What's the current working directory and the first 5 files in it?")
# The agent will autonomously call execute_shell_command("pwd && ls | head -n 5")

Available auto-generated tools:

execute_python_code(code: str) -> str — runs Python in the sandbox, returns stdout or error
execute_shell_command(command: str) -> str — runs shell command in the sandbox, returns output or error

Sandbox Backends

Choose the right backend for your security and performance needs:

Fastest, minimal isolation - development only

from praisonaiagents import SandboxConfig

config = SandboxConfig.subprocess()
agent = Agent(sandbox=config)

Requirements	None (built-in)
Use case	Development, trusted code only
Isolation	⚠️ Limited - NOT for untrusted code
Performance	✅ Fastest

POSIX (Linux/macOS): Subprocess now blocks host env leakage, enforces memory_mb/max_processes/max_open_files via setrlimit, truncates output at max_output_size, and terminates the whole process group on timeout.
Windows: Still weaker — setrlimit and process-group kill are unavailable; the sandbox warns at runtime.
Untrusted code: Remains a Docker/E2B job, but the gap is now smaller.

Full container isolation - recommended for production

from praisonaiagents import SandboxConfig

config = SandboxConfig.docker("python:3.11-slim")
agent = Agent(sandbox=config)

Requirements	Docker daemon + `pip install praisonaiagents[sandbox-docker]`
Use case	Production, untrusted code, full isolation
Isolation	✅ Complete container isolation
Performance	Good

Scalable cloud VMs with full filesystem access

import os
from praisonaiagents import SandboxConfig

os.environ["E2B_API_KEY"] = "your-api-key"
config = SandboxConfig.e2b()
agent = Agent(sandbox=config)

Requirements	`E2B_API_KEY` + `pip install praisonaiagents[sandbox] e2b-code-interpreter`
Use case	Cloud, scalable, full filesystem + shell
Isolation	✅ Cloud VM isolation
Performance	Good (network dependent)

OS-level sandboxing without Docker

from praisonaiagents import SandboxConfig

config = SandboxConfig.native(
    writable_paths=["./src", "./tests"],
    network=False,
)
agent = Agent(sandbox=config)

Requirements	macOS (Seatbelt) or Linux (Landlock + bubblewrap)
Use case	OS-native isolation without Docker
Isolation	✅ OS-level sandboxing
Performance	Good

Native sandbox parameters:

Param	Type	Default	Description
`writable_paths`	`List[str]`	`[os.getcwd()]`	Directories the agent may write to
`network`	`bool`	`False`	Whether to allow network access

OS-native sandboxing library

# Requires: pip install sandlock
config = SandboxConfig(sandbox_type="sandlock")

Requirements	`pip install sandlock`
Use case	OS-native sandboxing
Isolation	✅ OS-level isolation

Execute on remote servers via SSH

# Requires: pip install paramiko
config = SandboxConfig(sandbox_type="ssh")

Requirements	`pip install paramiko` + SSH access
Use case	Remote SSH execution
Isolation	Depends on remote system

Modal cloud compute platform

# Requires: pip install modal
config = SandboxConfig(sandbox_type="modal")

Requirements	`pip install modal` + Modal account
Use case	Modal cloud compute
Isolation	✅ Cloud isolation

Daytona development workspaces

# Requires: Daytona client
config = SandboxConfig(sandbox_type="daytona")

Requirements	Daytona client + workspace access
Use case	Daytona workspaces
Isolation	✅ Workspace isolation

All backend imports are lazy-loaded. Importing the top-level package will not trigger heavy backend imports.

What SecurityPolicy actually controls in subprocess

Setting	Effect on subprocess child
`allow_network=False`	Strips `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` from child env
`allow_network=True`	Passes proxy vars through from host
`max_output_size`	Truncates stdout/stderr; appends `[OUTPUT TRUNCATED]`
`allow_file_write`	Controls file write permissions (implementation varies by backend)
`allow_subprocess`	Controls subprocess creation (implementation varies by backend)
`blocked_paths`	Prevents access to specified paths
`blocked_commands`	Blocks execution of specified shell commands
`blocked_imports`	Prevents importing specified Python modules

Resource limits in practice

Linux / macOS
Windows

POSIX setrlimit mapping enforces hard limits:

from praisonaiagents import ResourceLimits

limits = ResourceLimits(
    memory_mb=512,        # → RLIMIT_AS 
    max_processes=10,     # → RLIMIT_NPROC
    max_open_files=50,    # → RLIMIT_NOFILE
    timeout_seconds=30    # Wall clock timeout (separate)
)

When limits are exceeded:

Memory: Process is killed by the kernel
Processes: fork() fails with EAGAIN
Files: open() fails with EMFILE
Timeout: Whole process group killed with SIGKILL

Resource limits are not available on Windows. The subprocess warns at runtime:

WARNING: Resource limits not supported on Windows - sandbox isolation is weaker

Only timeout handling works:

Timeout: Process leader is killed (not process group)
Memory/processes/files: No enforcement

For Windows users requiring resource limits, use Docker backend instead.

Timeout handling

On POSIX the whole process group is killed (killpg(SIGKILL)); on Windows only the leader is killed.

Subprocess execution flow

Security Pre-checks

Static code analysis warns about potentially dangerous patterns before execution:

from praisonaiagents.sandbox import check_code_safety, format_warnings

code = """
import os
os.system("rm -rf /tmp/test")
"""

warnings = check_code_safety(code, language="python")
print(format_warnings(warnings))
# Security analysis found 1 potential issue(s):
# HIGH RISK:
#   - Direct system command execution (line 3)
#     Context: os.system("rm -rf /tmp/test")
# Note: These are warnings only. The sandbox provides real isolation.

Security API

from praisonaiagents.sandbox import (
    check_code_safety,
    format_warnings,
    get_security_summary,
    SecurityWarning,
)

Function	Signature	Description
`check_code_safety`	`(code: str, language: str = "python") -> List[SecurityWarning]`	Runs regex + AST analysis. Supports `python`, `bash`, generic fallback
`format_warnings`	`(warnings: List[SecurityWarning]) -> str`	Pretty-print warnings grouped by severity
`get_security_summary`	`(warnings) -> Dict`	Returns `{"total_warnings", "by_severity", "max_severity", "is_safe", "has_critical"}`

SecurityWarning fields:

Field	Type	Description
`pattern`	`str`	Regex pattern or AST node that triggered
`message`	`str`	Human-readable warning
`severity`	`str`	`"low"`, `"medium"`, `"high"`, `"critical"`
`line_number`	`Optional[int]`	Line number in code
`context`	`Optional[str]`	Source line text

Security pre-checks do not block execution - they provide warnings only. The sandbox provides the real isolation.

Agent Integration

Agents automatically run security checks unless disabled:

result = await agent.execute_code(
    code="import os; os.system('ls')",
    check_security=True,  # default
)
# Warnings are stored in result.metadata["security_warnings"]

Path Traversal Protection

DockerSandbox and SubprocessSandbox validate every path passed to write_file, read_file, and list_files. Paths that resolve outside the sandbox root — via ../, absolute paths, or symlink escapes — are rejected:

# Inside an agent's sandbox
sandbox.write_file("../../../etc/passwd", "x")   # returns False, logs warning
sandbox.read_file("/etc/shadow")                  # returns None
sandbox.list_files("../..")                       # returns []

Blocked attempts are logged as Path traversal attempt blocked: <path>. This is in addition to the container/OS isolation the sandbox already provides — defense in depth.

SandboxManager

Factory and async context manager for sandbox backends:

from praisonaiagents.sandbox import SandboxManager, SandboxConfig

# Convenience: one-shot run
config = SandboxConfig.docker("python:3.11-slim")
manager = SandboxManager(config)
result = await manager.run_code("print('Hello, World!')")

# Context manager: reuse one sandbox for multiple executions
async with SandboxManager(config) as sandbox:
    r1 = await sandbox.execute("x = 5")
    r2 = await sandbox.execute("print(x * 2)")  # persistence depends on backend

SandboxManager API

Method	Description
`__init__(config: SandboxConfig \| None)`	Defaults to `SandboxConfig.subprocess()`
`run_code(code, language="python", **kwargs) -> SandboxResult`	One-shot: open, run, cleanup
`__aenter__ / __aexit__`	Async context manager yielding `SandboxProtocol`
`get_available_types() -> Dict[str, Dict]`	Returns availability info per backend

Configuration Options

Progressive disclosure from simple to advanced:

from praisonaiagents import Agent, SandboxConfig, ResourceLimits, SecurityPolicy

# Level 1: Bool (simplest)
agent = Agent(sandbox=True)

# Level 2: Factory shortcut
agent = Agent(sandbox=SandboxConfig.docker("python:3.11-slim"))

# Level 3: Full config
agent = Agent(
    sandbox=SandboxConfig(
        sandbox_type="e2b",
        resource_limits=ResourceLimits(memory_mb=512, timeout_seconds=60),
        security_policy=SecurityPolicy.standard(),
    )
)

SandboxConfig Options

Option	Type	Default	Description
`sandbox_type`	`str`	`"subprocess"`	Backend: subprocess, docker, e2b, native, sandlock, ssh, modal, daytona
`image`	`str`	`"python:3.11-slim"`	Docker image (docker backend only)
`working_dir`	`str`	`"/workspace"`	Working directory within sandbox
`env`	`Dict[str, str]`	`{}`	Environment variables
`resource_limits`	`ResourceLimits`	`ResourceLimits()`	CPU, memory, timeout limits
`security_policy`	`SecurityPolicy`	`SecurityPolicy()`	File and network access rules
`auto_cleanup`	`bool`	`True`	Auto-cleanup after execution
`persist_files`	`bool`	`False`	Keep files between runs
`mount_paths`	`List[str]`	`[]`	Paths to mount (host:container format)
`metadata`	`Dict[str, Any]`	`{}`	Additional configuration

ResourceLimits Presets

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

Limit	Minimal	Standard	Generous
`memory_mb`	128	512	2048
`timeout_seconds`	30	60	300
`cpu_percent`	50	100	100
`network_enabled`	❌	❌	✅

SecurityPolicy Presets

from praisonaiagents import SecurityPolicy

# Strict policy for untrusted code
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"]
)

Common Patterns

Data Science Agent
Secure Code Review
Batch Processing

from praisonaiagents import Agent, SandboxConfig, ResourceLimits

agent = Agent(
    name="DataScientist",
    instructions="Analyze data and create visualizations.",
    sandbox=SandboxConfig(
        sandbox_type="docker",
        image="python:3.11-slim",
        resource_limits=ResourceLimits.generous(),  # Need memory for data
        mount_paths=["./data:/workspace/data:ro"],   # Mount data read-only
    )
)

agent.start("Load the CSV file and show descriptive statistics")

from praisonaiagents import Agent, SandboxConfig, SecurityPolicy

agent = Agent(
    name="SecurityReviewer", 
    instructions="Review code for security issues.",
    sandbox=SandboxConfig(
        sandbox_type="e2b",
        security_policy=SecurityPolicy.strict(),  # Maximum security
    )
)

agent.start("Analyze this code for potential vulnerabilities")

from praisonaiagents.sandbox import SandboxManager, SandboxConfig

config = SandboxConfig(
    sandbox_type="docker",
    persist_files=True,    # Keep files between runs
    auto_cleanup=False     # Manual cleanup
)

# Process multiple files using same sandbox
async with SandboxManager(config) as sandbox:
    for file in files:
        result = await sandbox.execute(f"process_file('{file}')")
        print(result.stdout)

Timeout Behavior & Resource Cleanup

Understanding how different backends handle timeouts and resource cleanup ensures your resource limits are properly enforced.

Backend	Local cleanup on timeout	Remote cleanup on timeout
`subprocess`	Process killed	N/A
`docker`	Client process killed and `docker kill <container>` issued on the named container (`praisonai-<execution_id>`)	Container stopped — resource limits enforced
`ssh`	Local SSH client killed	Remote process terminated via `timeout N sh -c ...` wrapper; remote temp file cleaned up via `finally` (even on error)
`e2b`, `modal`, `native`, `sandlock`, `daytona`	Backend-managed	Backend-managed

Docker Timeout Handling

Docker containers get deterministic names and are properly killed on timeout: Why containers are no longer orphaned: Every docker run is launched with --name praisonai-<execution_id>. On timeout, the sandbox issues docker kill <name> to stop the actual container — not just detach the client. Your memory_mb and cpu_percent limits are now enforced through the entire execution lifecycle.

SSH Timeout Handling

SSH backend prevents both remote process leaks and temp file accumulation: Remote process cleanup: Commands are wrapped with timeout N sh -c ... to ensure remote processes terminate even if the SSH connection drops. Temp file cleanup: File cleanup (rm -f) is now in a finally block. Even if execution raises (timeout, network blip), the remote temp file is removed. Cleanup errors are swallowed so they never mask the real execution result.

Best Practices

Use Docker for untrusted code

Always use Docker sandbox when executing code from untrusted sources. Subprocess isolation is not sufficient for security-critical applications.

Enable security pre-checks

Keep check_security=True (default) when calling execute_code(). Review warnings in result.metadata["security_warnings"] for insights.

Set appropriate resource limits

Configure memory and timeout limits based on expected workload. Start with minimal limits and increase as needed.

Disable network by default

Keep allow_network=False unless code specifically needs network access. This prevents data exfiltration.

Use context managers for persistence

For multiple operations on the same sandbox, use async with SandboxManager(config) as sandbox: to reuse the environment efficiently.

File system boundaries are enforced

Filesystem boundaries are enforced — write_file/read_file/list_files reject paths that escape the sandbox root, even before the backend’s isolation kicks in.

Sandboxed Agent

Complete agent with built-in sandbox

Tools

Extend agent capabilities

​Quick Start

​Agent Sandbox API

​SandboxMixin API

​Auto-Generated Agent Tools

​Sandbox Backends

​What SecurityPolicy actually controls in subprocess

​Resource limits in practice

​Timeout handling

​Subprocess execution flow

​Security Pre-checks

​Security API

​Agent Integration

​Path Traversal Protection

​SandboxManager

​SandboxManager API

​Configuration Options

​SandboxConfig Options

​ResourceLimits Presets

​SecurityPolicy Presets

​Common Patterns

​Timeout Behavior & Resource Cleanup

​Docker Timeout Handling

​SSH Timeout Handling

​Best Practices

​Related

Sandboxed Agent

Tools

Quick Start

Agent Sandbox API

SandboxMixin API

Auto-Generated Agent Tools

Sandbox Backends

What SecurityPolicy actually controls in subprocess

Resource limits in practice

Timeout handling

Subprocess execution flow

Security Pre-checks

Security API

Agent Integration

Path Traversal Protection

SandboxManager

SandboxManager API

Configuration Options

SandboxConfig Options

ResourceLimits Presets

SecurityPolicy Presets

Common Patterns

Timeout Behavior & Resource Cleanup

Docker Timeout Handling

SSH Timeout Handling

Best Practices

Related