This guide walks you through the fastest path to a working OpenSandbox setup: spin up the server locally, install the Python SDK, run a command inside a sandbox, and try the CLI. The entire flow takes under 10 minutes.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/opensandbox-group/OpenSandbox/llms.txt
Use this file to discover all available pages before exploring further.
The OpenSandbox server must be running before you can use any SDK or CLI command. Complete Step 2 before proceeding to the SDK or CLI steps.
uvpip also worksGenerate a starter configuration file for the Docker runtime, then start the server. The
uvx command runs the server without a permanent install — useful for trying it out.# Generate a Docker-runtime config at the default path
uvx opensandbox-server init-config ~/.sandbox.toml --example docker
# Start the server (reads ~/.sandbox.toml by default)
uvx opensandbox-server
For non-interactive environments (Docker, CI), set
OPENSANDBOX_INSECURE_SERVER=YES if you have not configured an API key yet. See the Configuration guide for authentication details.Install the base Sandbox SDK. If you also want to use the Code Interpreter (used in the next step), install that package separately.
The example below shows the full Python async workflow: creating a sandbox, running a shell command, writing and reading a file, running Python code through the Code Interpreter, and cleaning up.
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.1.0",
entrypoint=["/opt/code-interpreter/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 (single-run, pass language directly)
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())
osb config init
osb config set connection.domain localhost:8080
osb config set connection.protocol http
Use
osb config set connection.domain localhost:8080 once and every subsequent command will target your local server automatically. Add connection.api_key if you set server.api_key in your TOML config.# Create a Python 3.12 sandbox (30-minute timeout)
osb sandbox create --image python:3.12 --timeout 30m -o json
# Run a command (replace <id> with the sandbox ID from the output above)
osb command run <id> -o raw -- python -c "print(1 + 1)"
Next Steps
SDKs Overview
Explore all SDK languages — Python, JavaScript/TypeScript, Kotlin/Java, Go, and C#/.NET.
CLI Reference
Full command reference for
osb, including file operations, egress policy, and diagnostics.MCP Server
Connect OpenSandbox to Claude Code, Cursor, or any MCP-compatible client.
Credential Vault
Securely inject credentials into sandboxes without exposing secrets to workloads.