Sandbox Guarantees

Each isolation surface in PraisonAI guarantees something different — this page states exactly what, so you never mistake a restriction flag for a real boundary.

Quick Start

Isolate an explicit execute_code() call

Agent(sandbox=…) gives you the caller-invoked execute_code() API. It adds no tools and does not isolate tools= callables.

from praisonaiagents import Agent

agent = Agent(name="Coder", instructions="Run Python.", sandbox=True)
result = agent.execute_code_sync("print(2 + 2)")
print(result.stdout)

Isolate everything the model runs

AgentFlow(run_on="docker") puts the whole workflow inside a real container boundary, so model-driven shell and file tools route through the shared sandbox.

from praisonaiagents import Agent, AgentFlow

flow = AgentFlow(
    agents=[Agent(name="Builder", instructions="Build and run code.")],
    run_on="docker",  # docker | e2b | modal | daytona | flyio | tenki | local
)
flow.start("Write a script that prints the first 10 primes, then run it")

Guarantee Matrix

Each surface below isolates a different thing — read the row before you rely on it.

Surface	Isolates model-visible tools?	Isolates `tools=` callables?	Real container boundary?	Enforces `SecurityPolicy`?
`Agent(sandbox=True)` (default subprocess backend)	No — no tools auto-added	No	No (subprocess only)	Partial — `run_command()` only, not `execute()`
`Agent(sandbox=SandboxConfig(backend=...))` with real container backend	No — no tools auto-added	No	Yes (via configured backend)	Depends on backend
`AgentFlow(run_on="docker" \| "e2b" \| ...)`	Yes — shell/file tools route through the shared sandbox	No (callables stay in-process)	Yes	Depends on provider
`LocalAgent(compute="docker" \| "e2b" \| ...)`	Yes for that agent’s shell/file tools	No	Yes	Depends on provider
`SandboxedAgent(compute=...)`	Yes	No	Yes	Depends on provider

Why `sandbox=` is not a capability grant

Agent(sandbox=…) is a restriction flag, not a way to hand the model an execution tool.

Agent(sandbox=…) does not add execute_python_code / execute_shell_command to agent.tools — that auto-injection was reverted in PR #3976. Giving the model a sandboxed execution tool must be a deliberate act by the caller, the way MCP() is. No peer framework grants execution capability from a config flag.

The default subprocess backend enforces none of its own SecurityPolicy on the execute() path:

allow_network=False does not block outbound HTTPS.
blocked_paths=['~/.ssh', ...] does not stop reading an SSH private key.
blocked_imports=['subprocess', ...] does not stop import subprocess.
A separate process is not a security boundary.

For real containment, use a real container backend (docker / e2b) or AgentFlow(run_on=…).

praisonai-sandbox must be installed to run any sandbox backend — pip install praisonaiagents alone is not enough. Install a backend, e.g. pip install "praisonai-sandbox[docker]".

Common Patterns

Explicit code execution
Give the model a sandbox tool
Whole-workflow container

from praisonaiagents import Agent

agent = Agent(name="Analyst", instructions="Analyze data.", sandbox=True)
result = agent.execute_code_sync("import statistics; print(statistics.mean([1, 2, 3]))")
print(result.stdout)

from praisonaiagents import Agent

agent = Agent(name="Coder", instructions="Use run_code to answer.", 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 ""

agent.tools = [run_code]  # explicit, the way MCP() is
agent.start("Print the Python version")

from praisonaiagents import Agent, AgentFlow

flow = AgentFlow(
    agents=[Agent(name="Builder", instructions="Build and run code.")],
    run_on="e2b",
)
flow.start("Create and run a script that lists installed packages")

Best Practices

Treat sandbox= as a restriction, not a grant

Agent(sandbox=…) configures the explicit execute_code() API. It never hands the model a tool — add one yourself only when you intend the model to run code.

Use a real container for untrusted or model-driven code

The default subprocess backend is for trusted development only. For untrusted or model-driven execution, use AgentFlow(run_on="docker"), LocalAgent(compute="docker"), or a docker / e2b sandbox backend.

Remember autonomy= injects a host tool

With autonomy=True, the agent still carries the host execute_command tool. sandbox= does not protect that path — isolate the whole workflow with AgentFlow(run_on=…) instead.

Install a sandbox backend first

pip install praisonaiagents cannot execute any sandbox. Install praisonai-sandbox with the backend you need before relying on isolation.

Sandbox

Configure the explicit execute_code() API and choose a backend

Shared Sandbox

Share one container across every agent with run_on=

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Sandbox Guarantees

Quick Start

Guarantee Matrix

Why `sandbox=` is not a capability grant

Common Patterns

Best Practices

Sandbox

Shared Sandbox

​Quick Start

​Guarantee Matrix

​Why sandbox= is not a capability grant

​Common Patterns

​Best Practices

​Related

Sandbox

Shared Sandbox

Quick Start

Guarantee Matrix

Why `sandbox=` is not a capability grant

Common Patterns

Best Practices

Related