Sandbox

Secure isolated environment for executing untrusted code safely

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

Quick Start

1. 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")
   
2. 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")
   
3. 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:

Subprocess (Local)

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

Subprocess sandbox provides minimal isolation. Never use with untrusted code.

Docker

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

E2B Cloud

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)

Native OS

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

Sandlock

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

SSH Remote

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

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

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.

---

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"]

---

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

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")

Secure Code Review

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")

Batch Processing

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.

---

Related

Sandboxed Agent

Complete agent with built-in sandbox

Tools

Extend agent capabilities