Skip to main content

{ } 📦 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:

VariantIsolation LevelBest For
evalNone (Python exec)Development, testing
montyIn-process secure interpreterSafe, fast LLM snippets
dockerContainerIsolated execution
jupyterProcess (Jupyter kernel)Persistent notebook-style state
kaggleManaged notebook runtimeInteractive and batch runs
colabManaged notebook runtimeInteractive Colab-connected runs
modalManaged container runtimeEphemeral compute tasks
datalayerManaged VM/runtimeProduction and GPU workloads

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​