OpenSandbox SDK vs Code Interpreter SDK: Key Differences Explained

The OpenSandbox SDK provides a generic, low-level client for container lifecycle management, while the Code Interpreter SDK extends it with a high-level, stateful code execution layer supporting multiple languages and persistent sessions.

When building secure execution environments with the alibaba/OpenSandbox repository, understanding the architectural distinction between these two Python SDKs is critical for selecting the right abstraction level. While both SDKs share the same underlying transport and daemon infrastructure, they serve fundamentally different use cases—generic container orchestration versus specialized code execution with REPL-like state persistence.

Core Architectural Differences

Primary Design Goals

The OpenSandbox SDK operates as a thin client over the execd daemon, exposing primitives for sandbox lifecycle, filesystem operations, raw command execution, and health monitoring. It treats the sandbox as a generic isolated environment without assumptions about the runtime contents.

Conversely, the Code Interpreter SDK wraps the base sandbox with a domain-specific service layer that assumes the container runs the opensandbox/code-interpreter image. This adds multi-language runtime management, execution contexts that maintain variable state across calls, and structured output streaming via Server-Sent Events (SSE).

Service Stack Architecture

In opensandbox/adapters/factory.py, the OpenSandbox SDK constructs generic service adapters:

• SandboxService – lifecycle management
• FilesystemService – file read/write/delete operations
• CommandService – raw shell execution
• MetricsService – resource monitoring
• HealthService – readiness checks

The Code Interpreter SDK, implemented in code_interpreter/adapters/factory.py, inherits all generic adapters but injects an additional Codes service (Codes for async, CodesSync for blocking operations). This service communicates with language-specific endpoints in the interpreter daemon to manage execution contexts and handle language runtimes.

Key Classes and Entry Points

OpenSandbox SDK Core Classes

The primary entry points reside in the sandbox package:

• opensandbox.sandbox.Sandbox – The async client defined in sdks/sandbox/python/src/opensandbox/sandbox.py
• opensandbox.sync.sandbox.SandboxSync – The synchronous counterpart in sdks/sandbox/python/src/opensandbox/sync/sandbox.py

Both classes expose methods like create(), commands.run(), files.write(), and kill(), operating directly against the DEFAULT_EXECD_PORT.

Code Interpreter SDK Wrappers

The Code Interpreter SDK provides thin wrappers that accept a sandbox instance and overlay the code execution service:

• code_interpreter.code_interpreter.CodeInterpreter – Async wrapper in sdks/code-interpreter/python/src/code_interpreter/code_interpreter.py
• code_interpreter.sync.code_interpreter.CodeInterpreterSync – Sync version in sdks/code-interpreter/python/src/code_interpreter/sync/code_interpreter.py

These wrappers expose the codes property, which provides create_context() and run() methods implemented in sdks/code-interpreter/python/src/code_interpreter/services/code.py (async) and its sync counterpart.

Functional Capabilities Comparison

Execution Model and State Management

OpenSandbox SDK operates statelessly. Each call to sandbox.commands.run() executes in isolation without memory of previous commands. This model suits CI/CD pipelines, data processing scripts, or any scenario requiring clean, independent execution environments.

Code Interpreter SDK introduces stateful execution contexts. Through interpreter.codes.create_context(language), you obtain a persistent session where variables and imports survive across multiple run() calls. This enables REPL-like workflows essential for interactive notebooks, AI agent tool use, and educational platforms where code builds upon previous state.

Language Support and Runtime Environment

The OpenSandbox SDK is runtime-agnostic. It executes whatever binaries exist in the provided container image through shell commands. If you need Python, you must ensure python exists in your custom image.

The Code Interpreter SDK provides built-in multi-language support via the opensandbox/code-interpreter Docker image. As configured through environment variables like PYTHON_VERSION and JAVA_VERSION during sandbox creation, the SDK supports Python, Java, Go, Node.js, Bash, and other languages through the SupportedLanguage enum defined in sdks/code-interpreter/python/src/code_interpreter/models/code.py.

Implementation Examples

Basic Sandbox Operations (OpenSandbox SDK)

The following example demonstrates creating a generic sandbox and executing shell commands using the async client:

import asyncio
from datetime import timedelta
from opensandbox import Sandbox
from opensandbox.config import ConnectionConfig

async def basic_sandbox():
    cfg = ConnectionConfig(domain="api.opensandbox.io", api_key="YOUR_KEY")
    sbx = await Sandbox.create(
        "python:3.11",
        resource={"cpu": "1", "memory": "2Gi"},
        timeout=timedelta(minutes=15),
        connection_config=cfg,
    )
    async with sbx:
        exec_res = await sbx.commands.run("echo Hello from sandbox")
        print(exec_res.logs.stdout[0].text)
        await sbx.kill()

asyncio.run(basic_sandbox())

Key implementation: sdks/sandbox/python/src/opensandbox/sandbox.py

Stateful Code Execution (Code Interpreter SDK)

This example shows how the Code Interpreter SDK maintains variable state across execution calls using persistent contexts:

import asyncio
from datetime import timedelta
from opensandbox import Sandbox
from opensandbox.config import ConnectionConfig
from code_interpreter import CodeInterpreter
from code_interpreter.models.code import SupportedLanguage

async def code_interpreter_demo():
    cfg = ConnectionConfig(domain="api.opensandbox.io", api_key="YOUR_KEY")
    sbx = await Sandbox.create(
        "opensandbox/code-interpreter:v1.0.1",
        connection_config=cfg,
        env={
            "PYTHON_VERSION": "3.11",
            "JAVA_VERSION": "17",
        },
    )
    async with sbx:
        interpreter = await CodeInterpreter.create(sandbox=sbx)
        ctx = await interpreter.codes.create_context(SupportedLanguage.PYTHON)
        
        await interpreter.codes.run("x = 42", context=ctx)
        result = await interpreter.codes.run("print(x)", context=ctx)
        print(result.logs.stdout[0].text)

        await sbx.kill()

asyncio.run(code_interpreter_demo())

Key implementations: sdks/code-interpreter/python/src/code_interpreter/code_interpreter.py and sdks/code-interpreter/python/src/code_interpreter/services/code.py

Synchronous Usage Patterns

Both SDKs provide synchronous wrappers for blocking codebases:

from opensandbox.sync.sandbox import SandboxSync
from opensandbox.config import ConnectionConfigSync
from code_interpreter.sync.code_interpreter import CodeInterpreterSync
from code_interpreter.models.code import SupportedLanguage

cfg = ConnectionConfigSync(domain="api.opensandbox.io", api_key="YOUR_KEY")
sandbox = SandboxSync.create(
    "opensandbox/code-interpreter:v1.0.1",
    connection_config=cfg,
    env={"PYTHON_VERSION": "3.11"},
)

interpreter = CodeInterpreterSync.create(sandbox=sandbox)
ctx = interpreter.codes.create_context(SupportedLanguage.PYTHON)
interpreter.codes.run("a = 10", context=ctx)
res = interpreter.codes.run("print(a)", context=ctx)
print(res.logs.stdout[0].text)

sandbox.kill()
sandbox.close()

Key implementation: sdks/code-interpreter/python/src/code_interpreter/sync/code_interpreter.py

Summary

• OpenSandbox SDK provides generic, low-level container management through Sandbox and SandboxSync classes, handling lifecycle, filesystem, and command execution without language-specific assumptions.
• Code Interpreter SDK extends the base sandbox with CodeInterpreter and CodeInterpreterSync wrappers, adding the Codes service for stateful, multi-language execution contexts and REPL-like variable persistence.
• Service Architecture differs in adapter composition: OpenSandbox uses generic adapters (SandboxService, CommandService, etc.) from opensandbox.adapters, while Code Interpreter injects an additional Codes adapter via code_interpreter.adapters.factory.
• State Management represents the primary functional gap: OpenSandbox executes stateless shell commands, whereas Code Interpreter maintains execution contexts where variables survive across run() calls.
• Runtime Requirements vary: OpenSandbox works with any container image containing required binaries, while Code Interpreter requires the opensandbox/code-interpreter image with built-in language runtimes configurable via environment variables.

Frequently Asked Questions

Can I use the Code Interpreter SDK without the OpenSandbox SDK?

No, the Code Interpreter SDK depends on the OpenSandbox SDK as its foundation. The CodeInterpreter class requires a Sandbox instance passed to its create() method, as it wraps the underlying container to inject the code execution service layer. You must install both packages and import from opensandbox to instantiate the base sandbox before wrapping it with code_interpreter.

Which SDK should I choose for running user-submitted code in a web application?

Choose the Code Interpreter SDK when you need to execute arbitrary user code safely while maintaining state between executions, such as in notebook environments or AI agent tools. It provides the Codes service with create_context() and run() methods that handle multi-language support, variable persistence, and streaming output. Use the OpenSandbox SDK only if you need generic container orchestration without language-specific execution semantics.

How does state persistence work in the Code Interpreter SDK?

The Code Interpreter SDK implements stateful execution through contexts created via interpreter.codes.create_context(language). When you pass a context to interpreter.codes.run(code, context=ctx), the code executes within a persistent session where variables, imports, and memory state survive across multiple calls. This contrasts with the OpenSandbox SDK's sandbox.commands.run(), where each invocation is stateless and isolated from previous commands.

Are there performance differences between the two SDKs?

Both SDKs share identical transport layers using httpx.AsyncClient or httpx.Client configured through ConnectionConfig, and both communicate with the same execd daemon on DEFAULT_EXECD_PORT. Performance differences arise primarily from the Code Interpreter SDK's additional service layer and the overhead of maintaining language runtimes and execution contexts. The OpenSandbox SDK offers slightly lower latency for simple command execution since it bypasses the language-specific serialization and context management overhead required by the Code Interpreter's Codes service.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}