Sandbox

Secure isolated environment for executing untrusted code safely

Sandbox gives an agent the explicit execute_code() API for running code in an isolated environment — you invoke it directly, the model does not call it on its own.

from praisonaiagents import Agent

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

# You invoke the sandbox explicitly — the model is not given a tool:
result = agent.execute_code_sync("print(sum(range(11)))")
print(result.stdout)

The user asks the agent to execute generated code; work stays inside an isolated sandbox instead of the host shell.

Quick Start

1. Simple Usage

   Enable the sandbox with a single line, then invoke it explicitly with execute_code_sync().

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Coder",
       instructions="Analyze data with Python.",
       sandbox=True  # configures agent.execute_code(); adds NO tools
   )
   
   result = agent.execute_code_sync("print('Hello from the sandbox')")
   print(result.stdout)

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.12-slim")
   )
   
   result = agent.execute_code_sync("import pandas; print(pandas.__version__)")
   print(result.stdout)

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(),
       )
   )
   
   result = agent.execute_code_sync("print('processed securely')")
   print(result.stdout)

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

What sandbox= configures (and what it does NOT)

Agent(sandbox=…) configures the explicit, caller-invoked execution API only — agent.execute_code(), agent.execute_code_sync(), and agent.run_shell_command(). It does not add any tools to agent.tools, so the model gains no new capability from the flag alone.

Verify that no tools are attached — the model sees an empty tool list from sandbox= alone:

from praisonaiagents import Agent

agent = Agent(
    name="Coder",
    instructions="Analyze data with Python.",
    sandbox=True,  # configures agent.execute_code(); adds NO tools
)

assert not any(getattr(t, "__name__", "") == "execute_python_code" for t in agent.tools)
assert not any(getattr(t, "__name__", "") == "execute_shell_command" for t in agent.tools)

To let the model call the sandbox, add a tool explicitly — the same way you opt into MCP(). Giving the model a sandboxed execution tool is a deliberate act by the caller, never a side effect of sandbox=:

from praisonaiagents import Agent

agent = Agent(
    name="Coder",
    instructions="Use run_code to answer questions with Python.",
    sandbox=True,
)

def run_code(code: str) -> str:
    """Run Python in the agent's configured sandbox."""
    result = agent.execute_code_sync(code)
    return result.stdout or result.error or ""

# Hand the wrapper to the model explicitly:
agent.tools = [run_code]
agent.start("Calculate fibonacci(10) and print the result")

Scope: what sandbox= isolates

Agent(sandbox=…) isolates only code you invoke through the explicit agent.execute_code(...) / run_shell_command(...) API.

It does not isolate:

• Python callables passed via tools= — ordinary in-process functions that run on the host.
• Tools attached by other layers — e.g. autonomy=True injects a host execute_command tool that runs unsandboxed regardless of sandbox=.

from praisonaiagents import Agent

def read_file(path: str) -> str:
    # Runs in-process on the host, NOT inside the sandbox.
    return open(path).read()

agent = Agent(
    name="Analyst",
    instructions="Use tools to answer.",
    sandbox=True,      # only agent.execute_code(...) runs in the sandbox
    tools=[read_file], # this callable runs on the host, unchanged
)

Sandbox Backends

New import path

Backends now live in praisonai_sandbox. The old praisonai.sandbox path still works as a shim.

# New (recommended)
from praisonai_sandbox import DockerSandbox, SubprocessSandbox

# Backward-compatible shim (still works)
from praisonai.sandbox import SubprocessSandbox

Install just the backend you need with pip install "praisonai-sandbox[docker]" — see the praisonai-sandbox Package.

Choose the right backend for your security and performance needs:

from praisonaiagents import SandboxConfig

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

from praisonaiagents import SandboxConfig

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

from praisonaiagents import SandboxConfig
from praisonai_sandbox import DockerSandbox
import asyncio

async def demo():
    sandbox = DockerSandbox(config=SandboxConfig.docker("python:3.11-slim"))
    await sandbox.start()
    await sandbox.write_file("data.txt", "persisted")
    r = await sandbox.run_command("cat data.txt")
    print(r.stdout)   # "persisted"
    await sandbox.stop()

asyncio.run(demo())

import os
from praisonaiagents import SandboxConfig

os.environ.setdefault("E2B_API_KEY", os.getenv("E2B_API_KEY", ""))
config = SandboxConfig.e2b()
agent = Agent(sandbox=config)

from praisonaiagents import SandboxConfig

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

# New (recommended)
from praisonai_sandbox import SandlockSandbox
# Backward-compatible shim (still works): from praisonai.sandbox import SandlockSandbox
from praisonaiagents import SandboxConfig

config = SandboxConfig(sandbox_type="sandlock")

# Requires: pip install "praisonai-sandbox[ssh]"  (asyncssh)
config = SandboxConfig(sandbox_type="ssh")

# Requires: pip install "praisonai-sandbox[modal]"
config = SandboxConfig(sandbox_type="modal")

# ❌ Won't work on Modal — write_file returns False, execute_file cannot read it
await sandbox.write_file("script.py", "print('hi')")
result = await sandbox.execute_file("script.py")

# ✅ On Modal, pass the code directly
result = await sandbox.execute(code="print('hi')")

# ✅ Or use a backend that has file storage
config = SandboxConfig(sandbox_type="docker")  # or "subprocess", "ssh"

# Requires: pip install "praisonai-sandbox[novita]"  (+ NOVITA_API_KEY)
from praisonaiagents import Agent, SandboxConfig

agent = Agent(
    name="Coder",
    instructions="Run code in a Novita cloud sandbox.",
    sandbox=SandboxConfig.novita(),
)
agent.start("Print the Python version")

from praisonaiagents import SandboxConfig

config = SandboxConfig.capsule()   # security_policy=strict() applied automatically
agent = Agent(sandbox=config)

Which backend do I pick?

Pick a file-capable backend when your workflow writes, reads, or executes files; Modal runs code inline only.

What SecurityPolicy actually controls in subprocess

Enforcement of blocked_imports refuses execution before the interpreter is spawned:

from praisonaiagents import Agent, SandboxConfig, SecurityPolicy

agent = Agent(
    name="Coder",
    instructions="Run Python.",
    sandbox=SandboxConfig(security_policy=SecurityPolicy.strict()),
)

result = agent.execute_code_sync("import subprocess\nprint('RAN')")
# result.status.name == "FAILED"
# result.stderr contains "Security policy violation: Blocked import: subprocess"

Resource limits in practice

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

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

from praisonaiagents import ResourceLimits

limits = ResourceLimits(
    memory_mb=512,        # → --memory 512m
    max_processes=128,    # → --pids-limit 128 (floored at MIN_CONTAINER_PIDS)
    timeout_seconds=30,   # Wall clock timeout
)

Timeout handling

graph TB
    subgraph "Timeout Response"
        A[⏰ Timeout Triggered] --> B{🖥️ OS?}
        B -->|POSIX| C[💀 killpg(SIGKILL)]
        B -->|Windows| D[💀 proc.kill()]
        C --> E[🧹 Process Group Dead]
        D --> F[⚠️ Leader Only Dead]
    end

    classDef timeout fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef decision fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef result fill:#8B0000,stroke:#7C90A0,color:#fff

    class A timeout
    class B decision
    class C,D,E,F result

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

SecurityWarning fields:

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 reject every path passed to write_file, read_file, and list_files that resolves outside the sandbox root — via ../, absolute paths, or symlink escapes:

# 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.

Symlink-safe file I/O on Docker

Your write_file / read_file are symlink-race safe on the Docker backend — no change to how you call them:

from praisonaiagents import Agent, SandboxConfig

agent = Agent(
    name="Analyst",
    instructions="Write results to report.txt",
    sandbox=SandboxConfig.docker(image="python:3.12-slim"),
)

On Docker the sandbox directory is bind-mounted into the container, so any check that verifies a name string and then opens it can be raced from inside. A container running a loop of ln -s /etc/passwd notes.txt against repeated writes could swap the name between a regular file and a symlink and win the race — escaping to arbitrary host files and disclosing a host secret within a few hundred attempts.

No amount of stricter string checking fixes this: anything verified before the open can be invalidated after it.

The fix walks each path one component at a time relative to an open directory descriptor (dir_fd=) with O_NOFOLLOW at every step. A symlink substituted at any level fails the open instead of redirecting it. Two helpers in praisonai_sandbox._compat implement the walk:

On the docker backend, list_files() resolves symlinks on both sides — the sandbox root and every walked path — before comparing them, and silently drops any entry that would still resolve outside the sandbox root. This defends against the macOS /var → /private/var symlink and any similar case, so host paths are never returned:

sandbox.list_files("/")   # -> ['/a.txt', '/sub/b.txt']
                          # host paths like '../../private/var/folders/...' are never returned

SandboxManager

Factory and async context manager for sandbox backends:

from praisonaiagents.sandbox import SandboxManager, SandboxConfig

# Convenience: one-shot run
config = SandboxConfig.docker("python:3.12-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

Configuration Options

Progressive disclosure from simple to advanced. Every level below configures the explicit agent.execute_code() API; none adds a tool to agent.tools, and none isolates tools= callables.

from praisonaiagents import Agent, SandboxConfig, ResourceLimits, SecurityPolicy

# Level 1: Bool (simplest)
# Configures agent.execute_code(); gives the model NO tool; leaves tools= callables on the host.
agent = Agent(sandbox=True)

# Level 2: Factory shortcut
agent = Agent(sandbox=SandboxConfig.docker("python:3.12-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(),
    )
)

Factory Shortcuts

SandboxConfig Options

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

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

from praisonaiagents import Agent, SandboxConfig, ResourceLimits

agent = Agent(
    name="DataScientist",
    instructions="Analyze data and create visualizations.",
    sandbox=SandboxConfig(
        sandbox_type="docker",
        image="python:3.12-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.

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

Related