Sandbox CLI

Secure command execution in sandboxed environments

The --sandbox flag enables secure command execution with validation and restrictions. The praisonai sandbox command manages sandbox containers.

A dedicated praisonai-sandbox binary ships with the standalone praisonai-sandbox package for when you want sandboxing without the rest of the framework. Both CLIs share the same commands.

Quick Start

# Enable sandbox mode
praisonai "Run echo hello" --sandbox basic

# Check sandbox status
praisonai sandbox status

---

Sandbox Commands

praisonai sandbox <command> [OPTIONS]

Command	Description
run	Execute code in a registered sandbox backend
shell	Open an interactive shell inside a registered sandbox backend
backends	List registered backends and their availability
status	Check sandbox container status
explain	Explain sandbox configuration
list	List all sandbox containers
recreate	Recreate sandbox containers

---

Status

Check the status of sandbox containers:

praisonai sandbox status

Output:

Sandbox Status

Container: praisonai-sandbox-main
  Status: Running
  Uptime: 2h 15m
  Memory: 256MB / 512MB
  CPU: 2%

Container: praisonai-sandbox-work
  Status: Stopped
  Last Run: 30m ago

With specific agent:

praisonai sandbox status --agent work

---

Explain

Explain the sandbox configuration for an agent:

praisonai sandbox explain

Output:

Sandbox Configuration

Mode: basic
Isolation Level: process

Allowed Commands:
  ✓ ls, cat, grep, find
  ✓ python, pip
  ✓ git (read-only)

Restricted:
  ✗ rm, mv (write operations)
  ✗ sudo, su (privilege escalation)
  ✗ curl, wget (network access)

Filesystem:
  Read: /home/user, /tmp
  Write: /tmp/sandbox
  Denied: /etc, /var, /usr

For specific agent:

praisonai sandbox explain --agent work

---

List

List all sandbox containers:

praisonai sandbox list

Output:

Sandbox Containers

NAME                        STATUS    CREATED         SIZE
praisonai-sandbox-main      Running   2 hours ago     45MB
praisonai-sandbox-work      Stopped   1 day ago       32MB
praisonai-sandbox-test      Exited    3 days ago      28MB

Output as JSON:

praisonai sandbox list --json

---

Recreate

Recreate sandbox containers (useful for updates or fixing issues):

praisonai sandbox recreate

Recreate specific container:

praisonai sandbox recreate --agent work

Force recreate all:

praisonai sandbox recreate --all --force

Option	Description
--agent NAME	Recreate for specific agent
--all	Recreate all containers
--force	Skip confirmation prompt

---

Run

Execute code in a registered sandbox backend using --type to select the backend.

praisonai sandbox run --code "print('hello')" --type subprocess

praisonai sandbox run --code "print('hello')" --type docker --image python:3.11-slim

If the requested backend isn’t installed, the CLI exits with code 2 and prints an install hint. Install optional backends with pip install "praisonai[docker]" (or modal, ssh, e2b, daytona). See Installing Optional Backends for the full matrix.

Flag	Default	Description
--code, -c	—	Inline code to execute
--file, -f	—	Path to a Python file to execute
--type, -t	subprocess	Sandbox backend name: subprocess, docker, e2b, modal, ssh, sandlock, or daytona
--image	python:3.11-slim	Docker image (docker backend only)
--timeout	60	Execution timeout in seconds

---

Shell

Open an interactive shell inside a registered sandbox backend.

praisonai sandbox shell --type subprocess

Type exit or press Ctrl+D to quit the shell. If the backend isn’t installed, the CLI exits with code 2 and prints a fix-it hint.

---

Backends

List every registered backend and whether it is installed and ready to use:

praisonai sandbox backends

Output:

Sandbox backends

NAME         AVAILABILITY   INSTALL HINT
subprocess   available      —
sandlock     available      —
docker       unavailable    pip install "praisonai[docker]"
ssh          unavailable    pip install "praisonai[ssh]"
modal        unavailable    pip install "praisonai[modal]"
e2b          unavailable    pip install "praisonai[e2b]"
daytona      unavailable    pip install "praisonai-sandbox[daytona]"

Unavailable backends show the exact install command. See Sandbox Backends for the full matrix and praisonai-sandbox Package for the slim standalone install.

---

Sandbox Modes

Mode	Description
off	No sandboxing (default)
basic	Basic isolation with command validation
strict	Strict isolation with filesystem restrictions

Usage with Prompts

Basic Mode

praisonai "Execute ls -la" --sandbox basic

Output:

🔒 Sandbox Mode: BASIC
Commands will be validated before execution

╭─────────────── 🔒 Tool Approval Required ───────────────╮
│ Function: execute_command                               │
│ Risk Level: CRITICAL                                    │
│ Arguments:                                              │
│   command: ls -la                                       │
╰─────────────────────────────────────────────────────────╯
Execute this critical risk tool? [y/n]:

Strict Mode

praisonai "Run python script.py" --sandbox strict

Strict mode adds additional restrictions:

• Filesystem access limited to current directory
• Network access may be restricted
• Resource limits applied

Combine with Other Features

# With auto-approve for low-risk commands
praisonai "List files" --sandbox basic --approve-level low

# With verbose output
praisonai "Run tests" --sandbox strict --verbose

# With bot
praisonai bot telegram --token $TOKEN --sandbox

Security Features

• Command Validation: All commands are validated before execution
• Risk Assessment: Commands are assigned risk levels (low, medium, high, critical)
• User Approval: Critical commands require explicit user approval
• Audit Trail: All executed commands are logged

Sandbox mode provides an additional layer of security but should not be considered a complete security solution. Always review commands before approving execution.

---

Related

Bot CLI

Deploy messaging bots with sandbox

Browser CLI

Browser automation

Sandbox Backends

All seven built-in backends, install commands, and backend selection guide

praisonai-sandbox Package

Slim standalone sandbox package and its praisonai-sandbox CLI