{ } 📦 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, snapshot)
• ✅ 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 Backends: eval, Docker, Jupyter, Monty, Kaggle, Colab, Modal, 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
• 🚀 GPU Support: Access GPU compute for ML workloads

Sandbox Variants​

Code Sandboxes supports these execution variants:

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)

Development​

Run the local test suite:

pytest tests/

Default local test suite environment variables:

• None for core local suites (eval, factory, model, and local Jupyter tests).

Optional integration test variables:

• DATALAYER_API_KEY for Datalayer runtime smoke tests.
• DATALAYER_RUN_URL for a custom Datalayer runtime URL.
• DATALAYER_ENVIRONMENT for Datalayer environment override.
• MODAL_TOKEN_ID and MODAL_TOKEN_SECRET for Modal integration tests.

CI Workflows​

This repository uses a reusable GitHub Actions workflow at .github/workflows/reusable-python.yml.

Workflows that call it:

• .github/workflows/build.yml
• .github/workflows/py-tests.yml
• .github/workflows/py-code-style.yml
• .github/workflows/py-typing.yml

Reusable workflow inputs:

• python-version
• install-system-deps
• install-extras
• extra-packages
• run-tests
• test-command
• run-mypy
• mypy-target
• run-pre-commit

Learn More​