Skip to main content

​
Quickstart Guide

This guide will walk you through creating and running your first OpenSandbox instance. You’ll learn how to install the server, start it, and execute commands in a sandbox using the Python SDK.

​
Prerequisites

Before you begin, ensure you have:
  • Docker (required for local execution)
  • Python 3.10+ (recommended for examples and local runtime)
  • uv or pip for package management
1

Install the Sandbox Server

Install the OpenSandbox server using uv or pip:
uv pip install opensandbox-server
2

Initialize Configuration

Create a configuration file for Docker runtime:
opensandbox-server init-config ~/.sandbox.toml --example docker
This creates a TOML configuration file with sensible defaults. For Kubernetes runtime, use --example k8s instead.
The configuration file includes server settings, runtime type, network mode, and security options. You can edit ~/.sandbox.toml to customize these settings.
3

Start the Server

Launch the sandbox server:
opensandbox-server
The server will start at http://0.0.0.0:8080 (or your configured host/port).To verify the server is running:
curl http://localhost:8080/health
Expected response:
{"status": "healthy"}
4

Install the Python SDK

Install the OpenSandbox Python SDK and Code Interpreter:
uv pip install opensandbox opensandbox-code-interpreter
5

Create and Use a Sandbox

Create a Python script to interact with your sandbox:
main.py
import asyncio
from datetime import timedelta

from code_interpreter import CodeInterpreter, SupportedLanguage
from opensandbox import Sandbox
from opensandbox.models import WriteEntry

async def main() -> None:
    # 1. Create a sandbox
    sandbox = await Sandbox.create(
        "opensandbox/code-interpreter:v1.0.1",
        entrypoint=["/opt/opensandbox/code-interpreter.sh"],
        env={"PYTHON_VERSION": "3.11"},
        timeout=timedelta(minutes=10),
    )

    async with sandbox:

        # 2. Execute a shell command
        execution = await sandbox.commands.run("echo 'Hello OpenSandbox!'")
        print(execution.logs.stdout[0].text)

        # 3. Write a file
        await sandbox.files.write_files([
            WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
        ])

        # 4. Read a file
        content = await sandbox.files.read_file("/tmp/hello.txt")
        print(f"Content: {content}")  # Content: Hello World

        # 5. Create a code interpreter
        interpreter = await CodeInterpreter.create(sandbox)

        # 6. Execute Python code
        result = await interpreter.codes.run(
            """
            import sys
            print(sys.version)
            result = 2 + 2
            result
            """,
            language=SupportedLanguage.PYTHON,
        )

        print(result.result[0].text)  # 4
        print(result.logs.stdout[0].text)  # 3.11.14

    # 7. Cleanup the sandbox
    await sandbox.kill()

if __name__ == "__main__":
    asyncio.run(main())
Run your script:
python main.py

​
What You Just Did

Congratulations! You’ve successfully:
  1. Installed and configured the OpenSandbox server
  2. Created a sandbox with a code interpreter environment
  3. Executed shell commands in the sandbox
  4. Performed file operations (write and read)
  5. Executed Python code and retrieved results
  6. Cleaned up the sandbox resources

​
Next Steps

Installation Guide

Explore detailed installation options for server and all SDKs

Python SDK

Learn more about the Python SDK features and configuration

Examples

Explore integration examples for coding agents, browsers, and more

API Reference

Dive into the complete API documentation

​
Synchronous API Example

If you prefer synchronous code, OpenSandbox provides a sync API: 
from datetime import timedelta
from opensandbox import SandboxSync
from opensandbox.config import ConnectionConfigSync

config = ConnectionConfigSync(
    domain="localhost:8080",
    request_timeout=timedelta(seconds=30),
)

sandbox = SandboxSync.create("ubuntu", connection_config=config)
with sandbox:
    execution = sandbox.commands.run("echo 'Hello Sandbox!'")
    print(execution.logs.stdout[0].text)
    sandbox.kill()

​
Troubleshooting

  • Ensure Docker is running: docker ps
  • Check port 8080 is not in use: lsof -i :8080
  • Verify the config file exists: cat ~/.sandbox.toml
  • Verify the server is healthy: curl http://localhost:8080/health
  • Check Docker can pull images: docker pull ubuntu
  • Review server logs for detailed error messages
  • Increase request_timeout in ConnectionConfig
  • Check network connectivity to the server
  • Ensure firewall rules allow traffic on port 8080

Build docs developers (and LLMs) love

Get started for freeTalk to us