{ } 📦 Code Sandboxes

Code Sandboxes is a Python package for creating safe, isolated environments where AI systems can write, run, and test code without affecting the real world or the user's device.

Package Scope

Code Sandboxes is the execution layer in the Datalayer AI stack:

This section clarifies what the package owns versus what is delegated to adjacent layers.

┌─────────────────────────────────────────────────────────────┐
│                     agent-runtimes                          │
│            (Agent hosting, protocols, UI)                   │
├──────────────────────────┬──────────────────────────────────┤
│      agent-codemode      │         agent-skills             │
│  (discovery, codegen)    │     (skills management)          │
├──────────────────────────┴──────────────────────────────────┤
│                    code-sandboxes                           │  ◀── You are here
│          (Safe code execution environment)                  │
└─────────────────────────────────────────────────────────────┘

Responsibilities:

• ✅ Execute Python/shell code safely in isolated environments
• ✅ Provide filesystem operations (read, write, list, upload, download)
• ✅ Run shell commands with streaming output
• ✅ Manage sandbox lifecycle (start, stop, and snapshot on datalayer)
• ✅ Support multiple execution variants through one API

Not Responsible For:

• ❌ MCP tool discovery or binding generation (→ agent-codemode)
• ❌ Skill management and composition (→ agent-skills)
• ❌ Agent protocols or UI components (→ agent-runtimes)

Key Features

• 🔒 Secure Isolation: Run untrusted code safely in sandboxed environments
• 🐍 Python Code Execution: Execute Python code with streaming output and rich results
• 📁 Filesystem Operations: Read, write, list, upload, and download files
• 💻 Command Execution: Run shell commands with streaming support
• 🧭 Unified Client API: Use CodeSandboxClient for variant-agnostic execution and streaming
• 📊 Detailed Status Reporting: Distinguish between infrastructure and code-level failures
• 🎯 Pydantic Models: Type-safe models with automatic validation and JSON serialization
• ⚡ Multiple Providers: eval, Docker, Jupyter, Monty, Kaggle, Colab, Modal, Daytona, E2B, CoreWeave, Cloudflare, and Datalayer
• 🔄 State Persistence: Maintain variables and context between executions
• 📊 Rich Output: Support for text, HTML, images, and structured data
• 📸 Snapshots: Save and restore sandbox state (datalayer)
• 🚀 GPU Support: Access GPU compute for ML workloads

Sandbox Variants

Code Sandboxes supports these execution variants:

Variant	Isolation Level	Best For
cloudflare	Managed container on the edge	Short snippets, each on its own
coreweave	Managed container	GPU work with a stateful session
datalayer	Managed VM/runtime	Production and GPU workloads
daytona	Managed cloud sandbox	Stateful agent sessions
docker	Container	Isolated execution
e2b	Firecracker microVM	Fast starts, stateful kernel, rich outputs
eval	None (Python exec)	Development, testing
google-colab	Managed notebook runtime	Interactive Colab-connected runs
jupyter-server	Process (Jupyter kernel)	Persistent notebook-style state
kaggle	Managed notebook runtime	Interactive and batch runs
modal	Managed container runtime	Ephemeral compute tasks
monty	In-process secure interpreter	Safe, fast LLM snippets

Quick Start

pip install code-sandboxes

Basic Usage

from code_sandboxes import Sandbox

with Sandbox.create() as sandbox:
    result = sandbox.run_code("print('Hello from the sandbox!')")
    print(result.stdout)  # Hello from the sandbox!

Execution Status Reporting

Code Sandboxes provides detailed status information for each execution:

result = sandbox.run_code("x = 1 / 0")

# Check infrastructure-level success
if not result.execution_ok:
    print(f"Sandbox failed: {result.execution_error}")
# Check explicit process exit (sys.exit)
elif result.exit_code not in (None, 0):
    print(f"Process exited with code: {result.exit_code}")

# Check code-level error (Python exception)
elif result.code_error:
    print(f"Python error: {result.code_error.name}: {result.code_error.value}")
    print(f"Traceback: {result.code_error.traceback}")

# Success!
else:
    print(f"Result: {result.text}")
    print(f"Duration: {result.duration:.2f}s")

# Convenience property
if result.success:
    print("Everything worked perfectly!")

Integration with Other Packages

With Agent Codemode

Code Sandboxes is used by agent-codemode to execute tool composition code:

from code_sandboxes import Sandbox
from agent_codemode import CodeModeExecutor, ToolRegistry

# agent-codemode uses code-sandboxes internally
executor = CodeModeExecutor(registry, sandbox_variant="datalayer")

With Agent Skills

Agent Skills uses Code Sandboxes to execute skill scripts:

from code_sandboxes import EvalSandbox
from agent_skills import SandboxExecutor

sandbox = EvalSandbox()
executor = SandboxExecutor(sandbox)

Learn More

📄️Code Sandboxes

123; } 📦 Code Sandboxes

📄️Guide

For Daytona, E2B, and Modal notebook execution, see

📄️Provider Ingress

Daytona, E2B, and Modal support two execution modes. New applications should

📄️Install

Basic Install

📄️CLI

Code Sandboxes ships a Typer CLI that does two things: it RUNS code in any

🗃Providers

12 items

📄️Examples

The Daytona, E2B, and Modal exec and repl examples use a real Jupyter

📄️API Reference

Sandbox Class

📄️Contribute

Code Sandboxes is developed in the open at

Contribute

Code Sandboxes is open source, and a new variant is a well-worn path: see Contribute for the development setup, the CI workflows, and what wiring up a provider takes.