Sandboxed Agent

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

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.

Not sure where the loop and the tools run? Run print(agent.where_does_it_run()) — see Where Your Agent Runs.

E2B/Docker execution now runs through the standalone praisonai-sandbox package under the hood — no user-visible change. The SandboxedAgent/SandboxedAgentConfig API is untouched. As of PR #4092, the vendor compute providers also live in that package (same names, same behaviour; old praisonai.integrations.compute.* imports still work through a shim).

Quick Start

Basic Usage

Local loop, local tools - simplest configuration.

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

With Tool Sandboxing

Local loop, tools run in E2B sandbox for security.

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

Component	Location	Purpose
Agent Loop	Local	LLM calls, decision making, memory
Tool Execution	Local or Sandbox	Code execution, file operations
Memory & State	Local	Session persistence, context

Configuration Options

SandboxedAgentConfig Reference

Full configuration options for sandboxed agents

Essential Configuration

Option	Type	Default	Description
`model`	`str`	`"gpt-4o"`	LLM model to use
`system`	`str`	`"You are a helpful coding assistant."`	System prompt
`tools`	`List[str]`	`["execute_command", "read_file", "write_file", "list_files", "search_web"]`	Available tools
`packages`	`Dict[str, List[str]]`	`None`	Package dependencies. PEP 508 specifiers only; pip options such as `--upgrade` or `-r file` are rejected with `ValueError`
`networking`	`Dict[str, Any]`	`{"type": "unrestricted"}`	Network access rules
`host_packages_ok`	`bool`	`False`	Allow host package installation

Common Patterns

Secure Development Environment

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

# 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

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

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

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

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

Rewrite options as plain specifiers:

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

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.

Requires base64 on the sandbox image’s $PATH — present on every stock PraisonAI compute image (Docker, E2B, Modal, Daytona, Novita, Fly.io). Bring-your-own minimal images must include it.

Multi-tenant Credential Isolation

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

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.

Managed Runtime Protocol

Remote agent runtime for full managed execution

Sandbox

Core SDK sandbox execution on agents

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)

Quick Start

How It Works

Configuration Options

SandboxedAgentConfig Reference

Essential Configuration

Common Patterns

Secure Development Environment

Local Development (No Sandbox)

Multi-Provider Flexibility

Best Practices

Managed Runtime Protocol

Sandbox

​Quick Start

​How It Works

​Configuration Options

SandboxedAgentConfig Reference

​Essential Configuration

​Common Patterns

​Secure Development Environment

​Local Development (No Sandbox)

​Multi-Provider Flexibility

​Best Practices

​Related

Managed Runtime Protocol

Sandbox

Quick Start

How It Works

Configuration Options

Essential Configuration

Common Patterns

Secure Development Environment

Local Development (No Sandbox)

Multi-Provider Flexibility

Best Practices

Related