praisonai-sandbox Package

Run agent code in isolated sandboxes without pulling in the full praisonai wrapper

Use praisonai-sandbox when you only need sandboxed execution — no gateway, no CLI wrapper — or when you want the sandbox backends on a slim install. It’s a standalone Tier‑2 package extracted from the praisonai wrapper, so agents keep the same sandbox=True behaviour with a much smaller dependency tree.

from praisonaiagents import Agent

agent = Agent(
    name="Coder",
    instructions="Run code safely",
    sandbox=True,  # subprocess backend, no extras needed
)
agent.start("Print the current directory tree")

The user asks the agent to run code; the sandbox package executes it in an isolated backend and returns the result.

Quick Start

1. Run an agent with the default backend

   The subprocess backend ships in the base install — nothing else to configure:

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Coder",
       instructions="Run code safely",
       sandbox=True,
   )
   agent.start("Print the current directory tree")
   
2. Install the slim package and optional backends

   pip install praisonai-sandbox                 # slim install, subprocess backend
   pip install "praisonai-sandbox[docker]"
   pip install "praisonai-sandbox[e2b]"
   pip install "praisonai-sandbox[modal]"
   pip install "praisonai-sandbox[ssh]"
   pip install "praisonai-sandbox[sandlock]"
   pip install "praisonai-sandbox[daytona]"      # pulls daytona-sdk; set DAYTONA_API_KEY
   pip install "praisonai-sandbox[all]"          # every backend at once
   
3. List available backends

   praisonai-sandbox backends
   

   daytona: unavailable
   docker: unavailable
   e2b: unavailable
   modal: unavailable
   sandlock: unavailable
   ssh: unavailable
   subprocess: available
   

   Each backend reports available or unavailable based on whether its optional dependency is installed.

The standalone praisonai-sandbox console script currently exposes --help and backends. To run code or open an interactive shell, use the wrapper CLI — praisonai sandbox run / praisonai sandbox shell (see Sandbox CLI).

Backends included

Every backend is selectable by name through praisonaiagents.sandbox.SandboxManager — the same registry the wrapper uses.

Name	Class	Typical use
subprocess	SubprocessSandbox	Fast local development (base install)
sandlock	SandlockSandbox	Hardened local sandbox ([sandlock])
docker	DockerSandbox	Container isolation for production ([docker])
ssh	SSHSandbox	Remote server execution ([ssh])
modal	ModalSandbox	Modal cloud sandboxes ([modal])
e2b	E2BSandbox	E2B cloud code interpreter ([e2b])
daytona	DaytonaSandbox	Daytona cloud sandboxes ([daytona] + DAYTONA_API_KEY)

Only subprocess ships in the base praisonai-sandbox install. Every other backend — including sandlock — requires its matching extra. This differs from the full praisonai wrapper, where subprocess and sandlock are both built in.

Use the backends directly

Import a backend class straight from the package when you want the isolated runtime without an Agent:

import asyncio
from praisonaiagents.sandbox import SandboxConfig, SandboxManager

async def main():
    manager = SandboxManager(SandboxConfig.subprocess())
    result = await manager.execute_code("print('hello from the sandbox')")
    print(result.output)

asyncio.run(main())

Best Practices

Install only the backends you use

The base package is intentionally slim. Add [docker], [e2b], [modal], [ssh], [sandlock], or [daytona] extras individually instead of [all] to keep the dependency tree small.

Set cloud credentials before selecting cloud backends

daytona needs DAYTONA_API_KEY (and optional DAYTONA_API_URL); e2b and modal need their own provider credentials. Selecting a backend without its credentials fails fast.

Check availability in CI

Run praisonai-sandbox backends in CI to confirm the expected backend is installed before a pipeline depends on it.

Prefer the wrapper CLI for run / shell

The standalone script lists backends; the praisonai sandbox run / shell commands execute code and open REPLs with full flag support.

Related

Sandbox Backends

All seven backends, the registry, and backend selection guide

Sandbox CLI

praisonai sandbox run, shell, and backends commands