# OpenSandbox SDK vs Code Interpreter SDK: Key Differences Explained

> Explore the OpenSandbox SDK vs Code Interpreter SDK. Discover key differences in container management and code execution capabilities for your next project.

- Repository: [Alibaba/OpenSandbox](https://github.com/alibaba/OpenSandbox)
- Tags: comparison
- Published: 2026-03-08

---

**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](https://github.com/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/sdks/sandbox/python/src/opensandbox/sandbox.py)
- **`opensandbox.sync.sandbox.SandboxSync`** – The synchronous counterpart in [`sdks/sandbox/python/src/opensandbox/sync/sandbox.py`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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`](https://github.com/alibaba/OpenSandbox/blob/main/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:

```python
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`](https://github.com/alibaba/OpenSandbox/blob/main/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:

```python
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`](https://github.com/alibaba/OpenSandbox/blob/main/sdks/code-interpreter/python/src/code_interpreter/code_interpreter.py) and [`sdks/code-interpreter/python/src/code_interpreter/services/code.py`](https://github.com/alibaba/OpenSandbox/blob/main/sdks/code-interpreter/python/src/code_interpreter/services/code.py)

### Synchronous Usage Patterns

Both SDKs provide synchronous wrappers for blocking codebases:

```python
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`](https://github.com/alibaba/OpenSandbox/blob/main/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.