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:
2

Initialize Configuration

Create a configuration file for Docker runtime:
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:
The server will start at http://0.0.0.0:8080 (or your configured host/port).To verify the server is running:
Expected response:
4

Install the Python SDK

Install the OpenSandbox Python SDK and Code Interpreter:
5

Create and Use a Sandbox

Create a Python script to interact with your sandbox:
main.py
Run your script:

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:

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