Praison AI

Sandboxed Agent

Local agent loop with optional tool sandboxing for secure execution

Sandboxed agents keep the agent loop local while optionally running tools in secure sandboxes.

python
from praisonai import SandboxedAgent, SandboxedAgentConfig
from praisonaiagents import Agent

sandboxed = SandboxedAgent(
    config=SandboxedAgentConfig(
        model="gpt-4o",
        system="You are a coding assistant.",
    )
)
agent = Agent(name="coder", backend=sandboxed)
agent.start("Create a Python script that prints hello")

The user asks the agent to run code; tool calls execute in E2B or Docker sandboxes instead of on the host.

Diagram

Sandboxed Agent Architecture

Sandboxed

Local

👤 User Input

🧠 Local Agent Loop

🔧 Tool Execution

📦 E2B/Docker

🖥️ Host System

✅ Result

Quick Start

  1. Basic Usage

    Local loop, local tools – simplest configuration.

    python
    from praisonai import SandboxedAgent, SandboxedAgentConfig
from praisonaiagents import Agent

sandboxed = SandboxedAgent(
    config=SandboxedAgentConfig(
        model="gpt-4o",
        system="You are a coding assistant.",
    )
)

agent = Agent(name="coder", backend=sandboxed)
result = agent.start("Create a Python script that prints hello")
  2. With Tool Sandboxing

    Local loop, tools run in E2B sandbox for security.

    python
    from praisonai import SandboxedAgent, SandboxedAgentConfig

sandboxed = SandboxedAgent(
    compute="e2b",  # Tools run in E2B, thinking stays local
    config=SandboxedAgentConfig(
        model="gpt-4o",
        system="You are a coding assistant.",
        tools=["execute_command", "read_file", "write_file"],
        packages={"pip": ["pandas", "numpy"]},
    )
)

agent = Agent(name="secure_coder", backend=sandboxed)
result = agent.start("Analyze CSV data with pandas")

How It Works

Diagram
SandboxToolsAgentLoopUserSandboxToolsAgentLoopUseralt[Tool sandboxing enabled][Local execution]“Create Python script”Determine tools neededExecute in E2B/DockerSecure resultExecute on hostTool outputGenerated script
ComponentLocationPurpose
Agent LoopLocalLLM calls, decision making, memory
Tool ExecutionLocal or SandboxCode execution, file operations
Memory & StateLocalSession persistence, context

Configuration Options

SandboxedAgentConfig Reference

Full configuration options for sandboxed agents

Essential Configuration

OptionTypeDefaultDescription
modelstr"gpt-4o"LLM model to use
systemstr"You are a helpful coding assistant."System prompt
toolsList[str]["execute_command", "read_file", "write_file", "list_files", "search_web"]Available tools
packagesDict[str, List[str]]NonePackage dependencies. PEP 508 specifiers only; pip options such as --upgrade or -r file are rejected with ValueError
networkingDict[str, Any]{"type": "unrestricted"}Network access rules
host_packages_okboolFalseAllow host package installation

Common Patterns

Secure Development Environment

python
# Development with package isolation
sandboxed = SandboxedAgent(
    compute="docker",
    config=SandboxedAgentConfig(
        model="claude-sonnet-4-6",
        tools=["execute_command", "read_file", "write_file"],
        packages={
            "pip": ["requests", "beautifulsoup4"],
            "npm": ["express", "lodash"]
        },
        networking={"type": "limited", "allowed_hosts": ["api.github.com"]}
    )
)

Local Development (No Sandbox)

python
# Fast iteration, local execution
sandboxed = SandboxedAgent(
    config=SandboxedAgentConfig(
        model="gpt-4o-mini",
        host_packages_ok=True,  # Allow host package installs
        tools=["execute_command", "search_web"]
    )
)

Multi-Provider Flexibility

python
# Use with any LLM provider
sandboxed = SandboxedAgent(
    config=SandboxedAgentConfig(
        model="ollama/llama3.3",  # Local model
        system="You are a Python expert.",
        tools=["execute_command"]
    )
)

Best Practices

Security Considerations

Always use sandboxing when running untrusted code or installing packages:

python
# Secure: Tools run in sandbox
SandboxedAgent(compute="e2b", config=config)

# Insecure: Tools run on host
SandboxedAgent(config=config)  # Only if you trust the code
Performance Optimization
  • Use local execution for trusted environments and faster iteration
  • Use sandbox for production or when handling user-generated code
  • Consider model choice: gpt-4o-mini for speed, claude-sonnet-4-6 for complex tasks
Backward Compatibility

LocalManagedAgent and SandboxedAgent are the same class:

python
# Both imports work identically
from praisonai import LocalManagedAgent, LocalManagedConfig
from praisonai import SandboxedAgent, SandboxedAgentConfig

# Same functionality
old_agent = LocalManagedAgent(config=LocalManagedConfig())
new_agent = SandboxedAgent(config=SandboxedAgentConfig())
Tool Sandboxing vs Managed Runtime
  • SandboxedAgent: Agent loop stays local, only tools may be sandboxed
  • Managed Runtime: Entire agent loop runs remotely (see Managed Runtime Protocol)
Package Specifier Validation

packages={"pip": [...]} accepts PEP 508 requirement specifiers only. Pip options with a leading dash are rejected: --upgrade, --pre, -r requirements.txt, -e ./pkg. An invalid entry raises:

text
ValueError: Invalid pip package specifier: '--upgrade'. Only pip requirement specifiers are allowed.

Rewrite options as plain specifiers:

python
# Rejected
config = SandboxedAgentConfig(packages={"pip": ["--upgrade"]})

# Accepted
config = SandboxedAgentConfig(packages={"pip": ["pandas>=2", "numpy"]})
Binary write_file and EOF-safe Content

write_file accepts bytes and no longer truncates content that contains an EOF line.

python
from praisonai import SandboxedAgent, SandboxedAgentConfig
from praisonaiagents import Agent

sandboxed = SandboxedAgent(
    compute="e2b",
    config=SandboxedAgentConfig(
        model="gpt-4o",
        tools=["write_file"],
    )
)
agent = Agent(name="writer", backend=sandboxed)
agent.start("Save these bytes to /tmp/out.bin: b'\\x00\\x01\\x02'")

Binary bytes round-trip exactly, and a line reading EOF inside the content no longer cuts the file short — every byte reaches the target.

Multi-tenant Credential Isolation

Two SandboxedAgent instances with different API keys stay isolated in the same process.

python
from praisonai import SandboxedAgent, SandboxedAgentConfig

openai_tenant = SandboxedAgent(
    api_key="sk-openai-tenant",
    config=SandboxedAgentConfig(model="gpt-4o")
)
anthropic_tenant = SandboxedAgent(
    api_key="sk-ant-tenant",
    api_base="https://api.anthropic.com",
    config=SandboxedAgentConfig(model="claude-sonnet-4-6")
)

PraisonAI passes api_key and base_url directly to the inner agent, so credentials never leak into os.environ or a spawned subprocess.

Related

Managed Runtime Protocol

Remote agent runtime for full managed execution

 Sandbox

Core SDK sandbox execution on agents