> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[🤖 Agent] --> P[📦 praisonai-sandbox]
    P --> S1[subprocess]
    P --> S2[docker]
    P --> S3[e2b]
    P --> S4[modal]
    P --> S5[ssh]
    P --> S6[sandlock]
    P --> S7[daytona]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef pkg fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef backend fill:#10B981,stroke:#7C90A0,color:#fff

    class A agent
    class P pkg
    class S1,S2,S3,S4,S5,S6,S7 backend
```

## Quick Start

<Steps>
  <Step title="Run an agent with the default backend">
    The `subprocess` backend ships in the base install — nothing else to configure:

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent

    agent = Agent(
        name="Coder",
        instructions="Run code safely",
        sandbox=True,
    )
    agent.start("Print the current directory tree")
    ```
  </Step>

  <Step title="Install the slim package and optional backends">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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
    ```
  </Step>

  <Step title="List available backends">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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.
  </Step>
</Steps>

<Note>
  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](/docs/cli/sandbox)).
</Note>

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

<Note>
  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.
</Note>

## Use the backends directly

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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Check availability in CI">
    Run `praisonai-sandbox backends` in CI to confirm the expected backend is installed before a pipeline depends on it.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Sandbox Backends" icon="shield" href="/docs/features/sandbox-backends">
    All seven backends, the registry, and backend selection guide
  </Card>

  <Card title="Sandbox CLI" icon="terminal" href="/docs/cli/sandbox">
    `praisonai sandbox run`, `shell`, and `backends` commands
  </Card>
</CardGroup>