OpenSandbox

https://open-sandbox.ai/
Admin
OpenSandbox provides a universal sandbox infrastructure for AI applications, allowing users to...
Tokens:327,094
Snippets:2,410
Trust Score:5.4
Update:1 day ago
Show doc for...
Tokens:
Raw
### Start OpenSandbox server

Source: https://open-sandbox.ai/examples/aio-sandbox

Installs the server package, initializes configuration with the Docker example, and starts the server. The server runs in the foreground and will keep the terminal session busy.

```shell
uv pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker
opensandbox-server
```

--------------------------------

### Install OpenSandbox server and initialize example config

Source: https://open-sandbox.ai/examples/agent-sandbox

Install the opensandbox-server package and generate the example configuration file for the agent-sandbox provider. The init-config command writes the example config to ~/.sandbox.toml.

```shell
uv pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker
```

--------------------------------

### Start OpenSandbox server

Source: https://open-sandbox.ai/examples/agent-sandbox

Instructions to install the server package, fetch the example config, update the configuration for the agent-sandbox provider, and start the server.

```APIDOC
## Start OpenSandbox server

### Description
Steps to install the OpenSandbox server package, initialize the configuration, update it for the agent-sandbox Kubernetes provider, and start the server.

### Installation
```shell
uv pip install opensandbox-server
opensandbox-server init-config ~/.sandbox.toml --example docker
```

### Configuration
Update `~/.sandbox.toml` with the following sections:

```toml
[runtime]
type = "kubernetes"
execd_image = "opensandbox/execd:v1.1.0"

[kubernetes]
namespace = "default"
# kubeconfig_path = "/absolute/path/to/kubeconfig"  # optional if running in-cluster
workload_provider = "agent-sandbox"

[agent_sandbox]
shutdown_policy = "Delete"
```

### Start Server
```shell
opensandbox-server
```
```

--------------------------------

### Install OpenSandbox and run Gemini CLI example

Source: https://open-sandbox.ai/examples/gemini-cli

Install the opensandbox package and run the example script. Requires SANDBOX_DOMAIN, SANDBOX_API_KEY, and GEMINI_API_KEY environment variables.

```shell
# Install OpenSandbox package
uv pip install opensandbox

# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY / GEMINI_API_KEY)
uv run python examples/gemini-cli/main.py
```

--------------------------------

### Install and run agent sandbox example

Source: https://open-sandbox.ai/examples/agent-sandbox

Install the opensandbox package and run the example script. The command 'uv pip install opensandbox' installs the package, and 'uv run python examples/agent-sandbox/main.py' executes the example.

```shell
uv pip install opensandbox
uv run python examples/agent-sandbox/main.py
```

--------------------------------

### Install and run from source

Source: https://open-sandbox.ai/sdks/mcp

Navigate to the sandbox Python directory, sync dependencies with uv, and start the MCP server.

```bash
cd sdks/mcp/sandbox/python
uv sync
uv run opensandbox-mcp
```

--------------------------------

### Install OpenSandbox and run the OpenCode example

Source: https://open-sandbox.ai/examples/opencode

Install the OpenSandbox package and run the example script. The default free model does not require an API key. The script installs OpenCode (`npm install -g opencode-ai@latest`) at runtime, creates an isolated working directory, and runs `opencode run` with a simple prompt.

```shell
# Install the OpenSandbox package
uv pip install opensandbox

# Run the example. The default free model does not require an API key.
uv run python examples/opencode/main.py
```

--------------------------------

### Start OpenSandbox Server

Source: https://open-sandbox.ai/examples/host-volume-mount

Clone the OpenSandbox repository, copy the example configuration, and run the server with uv.

```shell
git clone git@github.com:opensandbox-group/OpenSandbox.git
cd OpenSandbox/server
cp opensandbox_server/examples/example.config.toml ~/.sandbox.toml
uv sync && uv run python -m opensandbox_server.main
```

--------------------------------

### Install dependencies and run with default settings

Source: https://open-sandbox.ai/examples/openclaw

Install required Python packages and run the example script with default settings.

```shell
# Install dependencies
uv pip install opensandbox requests

# Run with default settings
uv run python examples/openclaw/main.py
```

--------------------------------

### Install Packages and Run Code Interpreter Example

Source: https://open-sandbox.ai/examples/code-interpreter

Install the required OpenSandbox packages and run the example script. Requires SANDBOX_DOMAIN and SANDBOX_API_KEY environment variables. The script creates a sandbox, runs Python code, prints output, and cleans up in a finally block.

```shell
# Install OpenSandbox packages
uv pip install opensandbox opensandbox-code-interpreter

# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY)
uv run python examples/code-interpreter/main.py
```

--------------------------------

### Java Quick Start

Source: https://open-sandbox.ai/sdks/kotlin

Java 11+ example that creates a sandbox, runs a shell command, and releases both remote and local resources. Requires the OpenSandbox service to be running.

```java
import com.alibaba.opensandbox.sandbox.Sandbox;
import com.alibaba.opensandbox.sandbox.config.ConnectionConfig;
import com.alibaba.opensandbox.sandbox.domain.exceptions.SandboxException;
import com.alibaba.opensandbox.sandbox.domain.models.execd.executions.Execution;

public class QuickStart {
    public static void main(String[] args) {
        // 1. Configure connection
        ConnectionConfig config = ConnectionConfig.builder()
            .domain("api.opensandbox.io")
            .apiKey("your-api-key")
            .build();

        // 2. Create a Sandbox using try-with-resources
        try (Sandbox sandbox = Sandbox.builder()
                .connectionConfig(config)
                .image("ubuntu")
                .build()) {

            try {
                Execution execution = sandbox.commands().run("echo 'Hello Sandbox!'");
                System.out.println(execution.getLogs().getStdout().get(0).getText());
            } finally {
                sandbox.kill();
            } // try-with-resources closes the client even if kill() fails.

        } catch (SandboxException e) {
            // Handle Sandbox specific exceptions
            System.err.println("Sandbox Error: [" + e.getError().getCode() + "] " + e.getError().getMessage());
            System.err.println("Request ID: " + e.getRequestId());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

--------------------------------

### Install OpenSandbox and run Claude example

Source: https://open-sandbox.ai/examples/claude-code

Install the OpenSandbox package and run the example script. Requires SANDBOX_DOMAIN, SANDBOX_API_KEY, and ANTHROPIC_AUTH_TOKEN. The script installs the Claude CLI at runtime and sends a simple request.

```shell
# Install OpenSandbox package
uv pip install opensandbox

# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY / ANTHROPIC_AUTH_TOKEN)
uv run python examples/claude-code/main.py
```

--------------------------------

### Run an OpenSandbox example

Source: https://open-sandbox.ai/examples/

Navigate to the example directory and run the main.py entry point. Most examples include a main.py file; follow each example's run instructions for other languages.

```bash
python main.py
```

--------------------------------

### Install dependencies and run the Google ADK example

Source: https://open-sandbox.ai/examples/google-adk

Install OpenSandbox and Google ADK dependencies, then run the example script. Requires SANDBOX_DOMAIN, SANDBOX_API_KEY, and GOOGLE_API_KEY environment variables.

```shell
# Install OpenSandbox + Google ADK deps
uv pip install opensandbox google-adk

# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY / GOOGLE_API_KEY)
uv run python examples/google-adk/main.py
```

--------------------------------

### Start k8s OpenSandbox Server

Source: https://open-sandbox.ai/examples/code-interpreter

Installs the opensandbox-server package, initializes a k8s example config, downloads the BatchSandbox template, and starts the server.

```shell
uv pip install opensandbox-server

# replace with your k8s cluster config, kubeconfig etc.
opensandbox-server init-config ~/.sandbox.toml --example k8s
curl -o ~/batchsandbox-template.yaml https://raw.githubusercontent.com/opensandbox-group/OpenSandbox/main/server/opensandbox_server/examples/example.batchsandbox-template.yaml

opensandbox-server
```

--------------------------------

### Install dependencies from project root

Source: https://open-sandbox.ai/examples/openclaw

Install the required Python packages for the example.

```shell
uv pip install opensandbox requests
```

--------------------------------

### Create and Access the Desktop Sandbox

Source: https://open-sandbox.ai/examples/desktop

Installs the OpenSandbox package and runs the example script that starts the desktop stack (Xvfb + XFCE + x11vnc) and launches noVNC/websockify. The sandbox stays alive for 5 minutes by default; interrupt with Ctrl+C.

```shell
# Install OpenSandbox package
uv pip install opensandbox

uv run python examples/desktop/main.py
```

--------------------------------

### Install and run from package

Source: https://open-sandbox.ai/sdks/mcp

Install the opensandbox-mcp package via pip and start the server.

```bash
pip install opensandbox-mcp
opensandbox-mcp
```

--------------------------------

### Install dependencies and run the LangGraph example

Source: https://open-sandbox.ai/examples/langgraph

Install OpenSandbox, LangGraph, and LangChain Anthropic dependencies, then run the example. Requires SANDBOX_DOMAIN, SANDBOX_API_KEY, and ANTHROPIC_API_KEY environment variables.

```shell
# Install OpenSandbox + LangGraph deps
uv pip install opensandbox langgraph langchain-anthropic

# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY / ANTHROPIC_API_KEY)
uv run python examples/langgraph/main.py
```

--------------------------------

### Install OpenSandbox and run Codex CLI example

Source: https://open-sandbox.ai/examples/codex-cli

Installs the OpenSandbox package and runs the example script. Requires SANDBOX_DOMAIN, SANDBOX_API_KEY, and OPENAI_API_KEY environment variables. The script installs the Codex CLI at runtime and executes a simple request.

```shell
# Install OpenSandbox package
uv pip install opensandbox

# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY / OPENAI_API_KEY)
uv run python examples/codex-cli/main.py
```

--------------------------------

### Install Go SDK

Source: https://open-sandbox.ai/getting-started/

Install the OpenSandbox Go SDK using go get.

```bash
go get github.com/alibaba/OpenSandbox/sdks/sandbox/go
```

--------------------------------

### Async Quick Start: Create sandbox and run command

Source: https://open-sandbox.ai/sdks/python

Asynchronous example that creates a sandbox, runs a shell command, prints the output, and destroys the sandbox. Requires the OpenSandbox service to be running. Handles SandboxException and general exceptions, printing error code, message, and request ID.

```python
import asyncio
from opensandbox.sandbox import Sandbox
from opensandbox.config import ConnectionConfig
from opensandbox.exceptions import SandboxException

async def main():
    # 1. Configure connection
    config = ConnectionConfig(
        domain="api.opensandbox.io",
        api_key="your-api-key"
    )

    # 2. Create a Sandbox
    try:
        sandbox = await Sandbox.create(
            "ubuntu",
            connection_config=config
        )
        try:
            # 3. Execute a shell command
            execution = await sandbox.commands.run("echo 'Hello Sandbox!'")

            # 4. Print output
            print(execution.logs.stdout[0].text)
        finally:
            # 5. Terminate the remote sandbox and close local resources
            await sandbox.destroy()

    except SandboxException as e:
        # Handle Sandbox specific exceptions
        print(f"Sandbox Error: [{e.error.code}] {e.error.message}")
        # Server logs can be correlated by this request id (if available)
        print(f"Request ID: {e.request_id}")
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Run the example with a real token

Source: https://open-sandbox.ai/examples/openclaw

Generate a random token and run the example script, which creates a sandbox and starts the OpenClaw gateway.

```shell
export OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)"
uv run python examples/openclaw/main.py
```

--------------------------------

### Run the pool example script

Source: https://open-sandbox.ai/examples/windows

Installs the OpenSandbox client and runs the pool example script. The script acquires a sandbox from the pool-win-example pool, prints endpoints, and runs a command.

```shell
uv pip install opensandbox
cd examples/windows
python main_use_pool.py
```

--------------------------------

### Startup validation output

Source: https://open-sandbox.ai/guides/secure-container

Example output when the server starts and validates the secure runtime. Shows the INFO messages for a successful validation.

```bash
$ opensandbox-server
INFO     Validating secure runtime for Docker backend
INFO     Docker OCI runtime 'runsc' is available: {...}
INFO     Application startup complete.
```

--------------------------------

### Run the Windows sandbox example

Source: https://open-sandbox.ai/examples/windows

Install the OpenSandbox client, navigate to the example directory, and run the main script. The script creates a Windows sandbox with dockurr/windows:latest and Windows 11, waits for it to become healthy, prints the execd, RDP (3389), and web console (8006) endpoints, and executes a test command.

```shell
uv pip install opensandbox
cd examples/windows
python main.py
```

--------------------------------

### Create and access the Qwen sandbox

Source: https://open-sandbox.ai/examples/qwen-code

Installs the OpenSandbox package, exports provider settings (API key, base URL, model name), and runs the example script. The script installs Qwen Code at runtime, writes a project-local settings file, and runs a headless prompt. The API key is only injected via the environment variable.

```shell
# Install OpenSandbox package
uv pip install opensandbox

# Export provider settings
export API_KEY=your-api-key
export BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export MODEL_NAME=qwen3-coder-plus

# Run the example
uv run python examples/qwen-code/main.py
```

--------------------------------

### Run main.py all

Source: https://open-sandbox.ai/examples/aks-kata

Creates a sandbox, runs every demo step, and deletes it at the end.

```bash
python3 main.py all
```

--------------------------------

### Run the end-to-end example

Source: https://open-sandbox.ai/examples/kubernetes-pvc-volume-mount

Sets environment variables and runs the example script. The script creates a sandbox, writes a marker file, kills it, then creates a second sandbox on the same PVC to confirm the marker persists.

```shell
export OPEN_SANDBOX_API_KEY=your-api-key
export OPEN_SANDBOX_BASE_URL=http://localhost:8080
export SANDBOX_PVC_NAME=my-pvc

python examples/kubernetes-pvc-volume-mount/main.py
```

--------------------------------

### Start the OpenSandbox server with uvx

Source: https://open-sandbox.ai/getting-started/

Generate a starter config and start the server. Requires Docker Engine 20.10+ and Python 3.10+.

```bash
# Generate a starter config
uvx opensandbox-server init-config ~/.sandbox.toml --example docker

# Start the server
uvx opensandbox-server
```

--------------------------------

### Install SDK from Source

Source: https://open-sandbox.ai/examples/host-volume-mount

Install the latest SDK from source because volume support is not yet in the released package. Use uv or pip inside a virtual environment.

```shell
# From the project root (recommended: use uv)
uv pip install -e sdks/sandbox/python

# Or use pip inside a virtual environment
# python3 -m venv .venv && source .venv/bin/activate
# pip install -e sdks/sandbox/python
```

--------------------------------

### Install and run the Deep Agents example

Source: https://open-sandbox.ai/examples/deep-agents

Install Deep Agents and the OpenSandbox backend, then run the example. Requires SANDBOX_DOMAIN and ANTHROPIC_API_KEY environment variables. The agent writes a Python script into the sandbox, runs it, and reports the output; the sandbox is destroyed on exit.

```shell
# Install Deep Agents + the OpenSandbox backend
uv pip install deepagents langchain-sandbox-opensandbox

# Run the example (requires SANDBOX_DOMAIN / ANTHROPIC_API_KEY)
uv run python examples/deep-agents/main.py
```

--------------------------------

### Install dependencies for AIO sandbox example

Source: https://open-sandbox.ai/examples/aio-sandbox

Installs the required Python packages (opensandbox and agent-sandbox) under the project root using uv.

```shell
uv pip install opensandbox agent-sandbox==0.0.18
```

--------------------------------

### Create Host Directories

Source: https://open-sandbox.ai/examples/host-volume-mount

Create the host directories and files needed for the mount examples, including a marker file and a CSV dataset for the subpath demo.

```shell
# Create a directory to share with sandboxes
mkdir -p /tmp/opensandbox-data
echo "hello-from-host" > /tmp/opensandbox-data/marker.txt

# Create a subdirectory for the subpath demo
mkdir -p /tmp/opensandbox-data/datasets/train
echo -e "id,value\n1,100\n2,200\n3,300" > /tmp/opensandbox-data/datasets/train/data.csv
```

--------------------------------

### Install and use OpenSandbox CLI

Source: https://open-sandbox.ai/getting-started/

Install the CLI and run commands to configure the connection, create a sandbox, run a command, and kill the sandbox.

```bash
pip install opensandbox-cli

osb config init
osb config set connection.domain localhost:8080
osb config set connection.protocol http
osb config set connection.use_server_proxy true
osb sandbox create --image python:3.12 --timeout 30m -o json
osb command run <sandbox-id> -o raw --argv -- python -c "print(1 + 1)"
osb sandbox kill <sandbox-id> -o json
```

--------------------------------

### Start OpenSandbox server

Source: https://open-sandbox.ai/examples/docker-ossfs-volume-mount

Command to start the OpenSandbox server after configuration. Requires Linux host OS, ossfs installed, FUSE support, and a writable mount root.

```bash
opensandbox-server

```

--------------------------------

### Quick Start: Create Sandbox and Run Command

Source: https://open-sandbox.ai/sdks/javascript

Requires Node.js 20+ with ES modules and top-level await. Ensure the OpenSandbox service is running before executing. Creates a sandbox, runs 'echo Hello Sandbox!', and releases resources in finally blocks. Handles SandboxException with error code and request ID.

```ts
import { ConnectionConfig, Sandbox, SandboxException } from "@alibaba-group/opensandbox";

const config = new ConnectionConfig({
  domain: "api.opensandbox.io",
  apiKey: "your-api-key",
  // protocol: "https",
  // requestTimeoutSeconds: 60,
});

try {
  const sandbox = await Sandbox.create({
    connectionConfig: config,
    image: "ubuntu",
    timeoutSeconds: 10 * 60,
  });

  try {
    const execution = await sandbox.commands.run("echo 'Hello Sandbox!'");
    console.log(execution.logs.stdout[0]?.text);
  } finally {
    try {
      await sandbox.kill();
    } finally {
      await sandbox.close();
    }
  }
} catch (err) {
  if (err instanceof SandboxException) {
    console.error(
      `Sandbox Error: [${err.error.code}] ${err.error.message ?? ""}`,
    );
    console.error(`Request ID: ${err.requestId ?? "N/A"}`);
  } else {
    console.error(err);
  }
}
```

--------------------------------

### Run rclone volume mount verification example

Source: https://open-sandbox.ai/examples/rclone-volume-mount

Installs the Python SDK and runs the verification example from the repository root. Requires environment variables OPEN_SANDBOX_DOMAIN, OPEN_SANDBOX_API_KEY, and SANDBOX_VOLUME_NAME. The example uses python:3.11 by default; SANDBOX_IMAGE can select another Linux image with python3.

```shell
uv pip install -e sdks/sandbox/python
export OPEN_SANDBOX_DOMAIN=localhost:8080
export OPEN_SANDBOX_API_KEY=your-api-key
export SANDBOX_VOLUME_NAME=opensandbox-rclone-demo
python examples/rclone-volume-mount/main.py
```

--------------------------------

### Change to example directory

Source: https://open-sandbox.ai/examples/aks-kata

Run from the example directory before executing main.py commands.

```bash
cd examples/aks-kata
```

--------------------------------

### Structured output for skills install

Source: https://open-sandbox.ai/cli/

Use -o json to get machine-readable output for scripts or agents.

```bash
osb skills install sandbox-lifecycle --target codex --scope project -o json
```

--------------------------------

### Create and access the Kimi sandbox

Source: https://open-sandbox.ai/examples/kimi-cli

Installs the OpenSandbox package and runs the example script. Requires SANDBOX_DOMAIN, SANDBOX_API_KEY, and KIMI_API_KEY environment variables. The script installs Kimi CLI at runtime and sends a simple request.

```shell
# Install OpenSandbox package
uv pip install opensandbox

# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY / KIMI_API_KEY)
uv run python examples/kimi-cli/main.py
```

--------------------------------

### Build the Desktop Sandbox Image

Source: https://open-sandbox.ai/examples/desktop

Builds the sandbox image with desktop and VNC components pre-installed. Run from the examples/desktop directory.

```shell
cd examples/desktop
docker build -t opensandbox/desktop:latest .
```

--------------------------------

### Startup validation error message

Source: https://open-sandbox.ai/guides/secure-container

Example error message when the configured runtime is not available. The server refuses to start and shows the available runtimes.

```text
ERROR    Configured Docker runtime 'runsc' is not available.
        Available runtimes: runc.
        Please install and configure it in /etc/docker/daemon.json.
```

--------------------------------

### Quick Start: Create Sandbox and Run Command

Source: https://open-sandbox.ai/sdks/csharp

Creates a sandbox with a connection config, runs a shell command, prints the output, and releases resources. Requires .NET 8+ with implicit usings and a running OpenSandbox service. Handles SandboxException with error code and request ID.

```csharp
using OpenSandbox;
using OpenSandbox.Config;
using OpenSandbox.Core;

var config = new ConnectionConfig(new ConnectionConfigOptions
{
    Domain = "api.opensandbox.io",
    ApiKey = "your-api-key",
    // Protocol = ConnectionProtocol.Https,
    // RequestTimeoutSeconds = 60,
});

try
{
    await using var sandbox = await Sandbox.CreateAsync(new SandboxCreateOptions
    {
        ConnectionConfig = config,
        Image = "ubuntu",
        TimeoutSeconds = 10 * 60,
    });

    try
    {
        var execution = await sandbox.Commands.RunAsync("echo 'Hello Sandbox!'");
        Console.WriteLine(execution.Logs.Stdout.FirstOrDefault()?.Text);
    }
    finally
    {
        await sandbox.KillAsync();
    } // await using releases the client even if KillAsync fails.
}
catch (SandboxException ex)
{
    Console.Error.WriteLine($"Sandbox Error: [{ex.Error.Code}] {ex.Error.Message}");
    Console.Error.WriteLine($"Request ID: {ex.RequestId}");
}
```
Tokens:
Raw