### Start OpenSandbox Server with Docker Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/aio-sandbox/README.md

Install the OpenSandbox server, initialize its configuration for Docker, and then start the server. The server runs in the foreground.

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

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

### Install Dependencies and Run Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/openclaw/README.md

Installs necessary Python packages and runs the OpenClaw gateway example using uv.

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

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

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

### Local Development Setup

Source: https://github.com/opensandbox-group/opensandbox/blob/main/docs/README.md

Installs dependencies and starts the development server for the OpenSandbox documentation site.

```bash
nvm use 22
cd docs
pnpm install
pnpm docs:dev
```

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

### Install Dependencies and Run Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/google-adk/README.md

Install necessary dependencies for OpenSandbox and Google ADK, then run the main example script. Ensure environment variables like SANDBOX_DOMAIN, SANDBOX_API_KEY, and GOOGLE_API_KEY are set.

```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
```

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

### Install Server Dependencies and Run

Source: https://github.com/opensandbox-group/opensandbox/blob/main/CONTRIBUTING.md

Installs server dependencies using uv, copies and configures the example config file, and then runs the server.

```bash
# Navigate to server directory
cd server

# Install dependencies
uv sync

# Copy example configuration from the source tree
cp server/opensandbox_server/examples/example.config.toml ~/.sandbox.toml

# Edit configuration for development
# Set [log] level = "DEBUG" and [server] api_key
nano ~/.sandbox.toml

# Run server
uv run python -m opensandbox_server.main
```

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

### Install OpenSandbox and Run Kimi CLI Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/kimi-cli/README.md

Install the OpenSandbox package and execute the Python script to run the Kimi CLI example. This script installs kimi-cli at runtime and sends a sample 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
```

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

### Install OpenSandbox Packages and Run Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/code-interpreter/README.md

Installs the necessary OpenSandbox packages and then executes a Python example script. This script requires SANDBOX_DOMAIN and SANDBOX_API_KEY environment variables to be set.

```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
```

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

### Install OpenSandbox and Run Gemini CLI Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/gemini-cli/README.md

Install the OpenSandbox package and then execute the Python example script. This script handles Gemini CLI installation and execution, requiring specific environment variables for authentication and configuration.

```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
```

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

### Set Up and Run Qwen Code Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/qwen-code/README.md

Install the OpenSandbox package, export necessary provider settings including API key and base URL, and then execute the Python example script to run Qwen Code.

```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
```

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

### Install Dependencies and Run Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/README.md

Install project dependencies using pip and execute the main Python script. Alternatively, use the provided Dockerfile.

```bash
pip install -r requirements.txt
python main.py
```

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

### Initial Setup for execd Development

Source: https://github.com/opensandbox-group/opensandbox/blob/main/components/execd/DEVELOPMENT.md

Clone the repository, navigate to the execd directory, download Go dependencies, and build the executable. Ensure Go 1.24+ is installed.

```bash
git clone https://github.com/alibaba/OpenSandbox.git
cd OpenSandbox/components/execd
go mod download
go build -o bin/execd .
```

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

### Start OpenSandbox Server

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/host-volume-mount/README.md

Clones the OpenSandbox repository, navigates to the server directory, copies the example configuration, and starts the server. Requires Git and uv (or pip).

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

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

### Quick Start: Create Sandbox and Run Shell Command

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/sandbox/kotlin/README.md

This example demonstrates how to configure a connection, create a sandbox instance, execute a shell command, and print its standard output. Ensure the OpenSandbox service is running before execution.

```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()) {

            // 3. Execute a shell command
            Execution execution = sandbox
                    .commands()
                    .run("echo 'Hello Sandbox!'");

            // 4. Print output
            System.out.println(execution.getLogs().getStdout().get(0).getText());

            // 5. Cleanup (sandbox.close() called automatically)
            // Note: kill() must be called explicitly if you want to terminate the remote sandbox instance immediately
            sandbox.kill();
        } 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 and Run Codex CLI Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/codex-cli/README.md

Install the OpenSandbox Python package and then run the example script. This script requires specific environment variables to be set for authentication and configuration.

```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 Python Dependencies for Nullclaw Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/nullclaw/README.md

Install the necessary Python packages, 'opensandbox' and 'requests', from the project root to run the Nullclaw gateway example.

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

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

### Run OpenClaw Example with Authentication Token

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/openclaw/README.md

Installs dependencies and runs the OpenClaw example, setting a random token for authentication.

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

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

### Install and Run Claude Code Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/claude-code/README.md

Install the OpenSandbox Python package and then run the main example script. This script requires specific environment variables to be set.

```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 Agent-Sandbox Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/agent-sandbox/README.md

Installs the OpenSandbox Python client and runs the agent-sandbox example script.

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

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

### Quick Start: Create Sandbox and Run Command

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/sandbox/javascript/README.md

This example demonstrates how to create a sandbox, execute a shell command, and handle potential sandbox errors. Ensure the OpenSandbox service is running before execution.

```typescript
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,
  });

  const execution = await sandbox.commands.run("echo 'Hello Sandbox!'");
  console.log(execution.logs.stdout[0]?.text);

  // Optional but recommended: terminate the remote instance when you are done.
  await sandbox.kill();
  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);
  }
}
```

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

### Install OpenSandbox Client and Run Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/windows/README.md

Installs the OpenSandbox client library and executes the main Python script to create and manage a Windows sandbox. This script automates sandbox creation, health checks, and endpoint retrieval.

```shell
uv pip install opensandbox
python main.py
```

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

### Install OpenSandbox Client and Run Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/code-interpreter/README.md

Installs the OpenSandbox client packages and executes a Python script to create, use, and terminate a code interpreter sandbox. Ensure SANDBOX_DOMAIN and SANDBOX_API_KEY environment variables are set if required.

```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_use_pool.py

```

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

### Local Server Startup

Source: https://github.com/opensandbox-group/opensandbox/blob/main/server/AGENTS.md

Commands to initialize the server configuration with Docker as the example runtime and to start the main FastAPI application.

```bash
cd server
uv run opensandbox-server init-config ~/.sandbox.toml --example docker
uv run python -m opensandbox_server.main
```

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

### Install OpenSandbox Server

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/agent-sandbox/README.md

Installs the OpenSandbox server package and fetches an example configuration for agent-sandbox.

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

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

### Install Go Packages

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sandboxes/code-interpreter/README.md

Install a Go package using the `go install` command. Replace `github.com/user/package` with the actual package path.

```bash
go install github.com/user/package@latest
```

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

### Install and Run from Package

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/mcp/sandbox/python/README.md

Install the OpenSandbox MCP server using pip and then run it.

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

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

### Start Egress Controller and Setup iptables Redirect

Source: https://github.com/opensandbox-group/opensandbox/blob/main/oseps/0001-fqdn-based-egress-control.md

Initiates the DNS proxy and configures iptables REDIRECT rules for DNS traffic. Requires CAP_NET_ADMIN capability; logs warnings and disables enforcement if setup fails.

```go
func (c *Controller) Start() error {
    if c.policy == nil || len(c.policy.Egress) == 0 {
        logs.Info("[egress] no network_policy, enforcing default deny-all")
    }

    // Start DNS Proxy on non-privileged port (no root needed)
    c.dnsProxy = NewDNSProxy(c.policy, "127.0.0.1:15353")
    if err := c.dnsProxy.Start(); err != nil {
        return fmt.Errorf("failed to start DNS proxy: %w", err)
    }

    // Setup iptables REDIRECT (requires CAP_NET_ADMIN, NOT root)
    if err := c.setupIptablesRedirect(); err != nil {
        logs.Warn("[egress] iptables setup failed: %v", err)
        logs.Warn("[egress] network_policy will NOT be enforced")
        logs.Warn("[egress] ensure sidecar has CAP_NET_ADMIN capability")
        return nil  // Continue running sidecar (other functionality still works)
    }

    logs.Info("[egress] network policy active (iptables REDIRECT mode)")
    return nil
}

func (c *Controller) setupIptablesRedirect() error {
    rules := [][]string{
        {"iptables", "-t", "nat", "-A", "OUTPUT", "-p", "udp",
         "--dport", "53", "-j", "REDIRECT", "--to-port", "15353"},
        {"iptables", "-t", "nat", "-A", "OUTPUT", "-p", "tcp",
         "--dport", "53", "-j", "REDIRECT", "--to-port", "15353"},
    }

    for _, args := range rules {
        cmd := exec.Command(args[0], args[1:]...)
        if output, err := cmd.CombinedOutput(); err != nil {
            return fmt.Errorf("%v failed: %w (output: %s)", args, err, output)
        }
    }
    return nil
}
```

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

### Run RL Training Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/rl-training/README.md

Installs the OpenSandbox client package and executes the RL training script within the sandbox environment.

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

# Run the example
uv run python examples/rl-training/main.py
```

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

### Manage Agent Skills

Source: https://github.com/opensandbox-group/opensandbox/blob/main/cli/README.md

Provides examples for listing, showing, installing, and uninstalling agent skills.

```bash
osb skills list
osb skills show sandbox-lifecycle
osb skills install sandbox-lifecycle --target codex --scope project
osb skills install --all-builtins --target codex --scope global
osb skills uninstall sandbox-troubleshooting --target claude --scope global
```

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

### Install SDK using pnpm

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/code-interpreter/javascript/README.md

Install the Alibaba Code Interpreter SDK using pnpm.

```bash
pnpm add @alibaba-group/opensandbox-code-interpreter
```

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

### Quick Start: Execute Python Code with Code Interpreter

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/code-interpreter/kotlin/README.md

This Java example demonstrates initializing the Code Interpreter client, configuring a sandbox for Python 3.11, running a simple Python script, and printing its standard output. Ensure you use the 'opensandbox/code-interpreter:v1.1.0' image and handle potential SandboxExceptions.

```java
import com.alibaba.opensandbox.codeinterpreter.CodeInterpreter;
import com.alibaba.opensandbox.codeinterpreter.domain.models.execd.executions.CodeContext;
import com.alibaba.opensandbox.sandbox.domain.models.execd.executions.Execution;
import com.alibaba.opensandbox.codeinterpreter.domain.models.execd.executions.RunCodeRequest;
import com.alibaba.opensandbox.codeinterpreter.domain.models.execd.executions.SupportedLanguage;
import com.alibaba.opensandbox.sandbox.Sandbox;
import com.alibaba.opensandbox.sandbox.config.ConnectionConfig;
import com.alibaba.opensandbox.sandbox.domain.exceptions.SandboxException;

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 with specific runtime configuration
        // Note: You must use the code-interpreter image
        // Use try-with-resources to ensure sandbox is closed
        try (Sandbox sandbox = Sandbox.builder()
                .connectionConfig(config)
                .image("opensandbox/code-interpreter:v1.1.0")
                .entrypoint("/opt/code-interpreter/code-interpreter.sh")
                .env("PYTHON_VERSION", "3.11") // Select specific language version
                .build()) {

            // 3. Create CodeInterpreter wrapper
            CodeInterpreter interpreter = CodeInterpreter.builder()
                .fromSandbox(sandbox)
                .build();

            // 4. Create an execution context (Python)
            CodeContext context = interpreter.codes().createContext(SupportedLanguage.PYTHON);

            // 5. Run code
            Execution result = interpreter.codes().run(
                RunCodeRequest.builder()
                    .code("import sys; print(f'Running on Python {sys.version}')")
                    .context(context)
                    .build()
            );

            // 6. Print output
            if (!result.getLogs().getStdout().isEmpty()) {
                System.out.println(result.getLogs().getStdout().get(0).getText());
            }

            // 7. Cleanup
            // Note: kill() terminates the remote instance; close() (auto-called) cleans up local resources
            sandbox.kill();
        } catch (SandboxException e) {
            // Handle Sandbox specific exceptions
            System.err.println("Sandbox Error: [" + e.getError().getCode() + "] " + e.getError().getMessage());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}
```

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

### Install SDK using yarn

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/code-interpreter/javascript/README.md

Install the Alibaba Code Interpreter SDK using yarn.

```bash
yarn add @alibaba-group/opensandbox-code-interpreter
```

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

### Install Alibaba Sandbox SDK via yarn

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/sandbox/javascript/README.md

Install the SDK using yarn. Ensure you have Node.js and yarn installed.

```bash
yarn add @alibaba-group/opensandbox
```

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

### Install SDK from Source

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/host-volume-mount/README.md

Installs the OpenSandbox Python SDK from its source code, which is necessary for using the latest volume support features. Recommends using uv for installation.

```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 SDK using npm

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/code-interpreter/javascript/README.md

Install the Alibaba Code Interpreter SDK using npm.

```bash
npm install @alibaba-group/opensandbox-code-interpreter
```

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

### Setup Project with uv

Source: https://github.com/opensandbox-group/opensandbox/blob/main/tests/python/README.md

Navigate to the python test directory and synchronize dependencies using uv.

```bash
cd tests/python
uv sync
```

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

### OpenSandbox CLI Quick Start

Source: https://github.com/opensandbox-group/opensandbox/blob/main/README.md

Initialize configuration, set connection details, create a sandbox, and run a command using the OpenSandbox CLI.

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

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

### Install Node.js Packages

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sandboxes/code-interpreter/README.md

Install Node.js packages globally using npm. This example installs the TypeScript compiler globally.

```bash
npm install -g typescript
```

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

### Start Local OpenSandbox Server

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/vscode/README.md

Initializes the OpenSandbox server configuration and starts the server locally. It uses a Docker example configuration.

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

```

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

### Setup and Run Unit Tests (envtest)

Source: https://github.com/opensandbox-group/opensandbox/blob/main/kubernetes/AGENTS.md

Sets up the environment for envtest-based unit tests and then runs them using Ginkgo/Gomega. Navigate to the kubernetes directory before running.

```bash
cd kubernetes
make setup-envtest
make test
```

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

### Install CRDs

Source: https://github.com/opensandbox-group/opensandbox/blob/main/kubernetes/examples/controller/README.md

Installs the Custom Resource Definitions (CRDs) required for the controller example. Run this command from the project's root directory.

```bash
kubectl apply -f config/crd/bases/
```

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

### Quick Start: Execute Python Code in Sandbox

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/code-interpreter/csharp/README.md

Demonstrates creating a sandbox, initializing the code interpreter, running a Python script, and handling output and errors.

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

var config = new ConnectionConfig(new ConnectionConfigOptions
{
    Domain = "api.opensandbox.io",
    ApiKey = "your-api-key"
});

try
{
    // Create sandbox with code-interpreter runtime image and entrypoint.
    await using var sandbox = await Sandbox.CreateAsync(new SandboxCreateOptions
    {
        ConnectionConfig = config,
        Image = "opensandbox/code-interpreter:v1.1.0",
        Entrypoint = new[] { "/opt/code-interpreter/code-interpreter.sh" },
        Env = new Dictionary<string, string>
        {
            ["PYTHON_VERSION"] = "3.11",
            ["JAVA_VERSION"] = "17",
            ["NODE_VERSION"] = "20",
            ["GO_VERSION"] = "1.24"
        },
        TimeoutSeconds = 15 * 60
    });

    var interpreter = await CodeInterpreter.CreateAsync(sandbox);
    var execution = await interpreter.Codes.RunAsync(
        "print('Hello, World!')",
        new RunCodeOptions { Language = SupportedLanguage.Python });

    foreach (var msg in execution.Logs.Stdout)
    {
        Console.Write(msg.Text);
    }

    await sandbox.KillAsync();
}
catch (SandboxException ex)
{
    Console.Error.WriteLine($"Sandbox Error: [{ex.Error.Code}] {ex.Error.Message}");
}
```

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

### Asynchronous Quick Start: Create Sandbox and Run Command

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/sandbox/python/README.md

Demonstrates creating an asynchronous sandbox, executing a shell command, printing its output, and ensuring cleanup. Requires the OpenSandbox service to be running.

```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
        )
        async with sandbox:

            # 3. Execute a shell command
            execution = await sandbox.commands.run("echo 'Hello Sandbox!'")

            # 4. Print output
            print(execution.logs.stdout[0].text)

            # 5. Cleanup (sandbox.close() called automatically)
            # Note: kill() must be called explicitly if you want to terminate the remote sandbox instance immediately
            await sandbox.kill()

    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 Chrome Example Script

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/chrome/README.md

Executes the main Python script for the Chrome example using OpenSandbox. This script likely handles sandbox creation and setup.

```shell
uv pip install opensandbox
uv run python examples/chrome/main.py
```

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

### Install OpenSandbox Controller with Custom Values File

Source: https://github.com/opensandbox-group/opensandbox/blob/main/kubernetes/README.md

Install the OpenSandbox Controller using a custom YAML file for configuration. This is recommended for complex or repeatable configurations. The example shows creating a values file and then using it for installation.

```sh
# Create a custom values file
cat > custom-values.yaml <<EOF
controller:
  replicaCount: 2
  resources:
    limits:
      cpu: 1000m
      memory: 512Mi
    requests:
      cpu: 100m
      memory: 128Mi
  logLevel: debug
EOF

# Install with custom values
helm install opensandbox-controller \
  https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.1.0/opensandbox-controller-0.1.0.tgz \
  --namespace opensandbox-system \
  --create-namespace \
  -f custom-values.yaml
```

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

### Start OpenSandbox Server on Kubernetes

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/windows/README.md

Initialize and start the OpenSandbox server within a Kubernetes environment. This involves installing the server package, initializing its configuration, and running the server process.

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

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

### Kubernetes Development Setup and Execution

Source: https://github.com/opensandbox-group/opensandbox/blob/main/kubernetes/DEVELOPMENT.md

Commands to set up the development environment, build the project, run unit tests, and execute the controller locally.

```bash
cd kubernetes

# Install tools and download envtest binaries
make setup-envtest

# Verify build
make build

# Run unit tests
make test

# Run locally against the current kubeconfig
make run
```

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

### Create Sandbox and Execute Command (C#)

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/sandbox/csharp/README.md

Example demonstrating how to create a sandbox, execute a shell command, and retrieve its output. Ensure the OpenSandbox service is running before execution.

```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,
    });

    var execution = await sandbox.Commands.RunAsync("echo 'Hello Sandbox!'");
    Console.WriteLine(execution.Logs.Stdout.FirstOrDefault()?.Text);

    // Optional but recommended: terminate the remote instance when you are done.
    await sandbox.KillAsync();
}
catch (SandboxException ex)
{
    Console.Error.WriteLine($"Sandbox Error: [{ex.Error.Code}] {ex.Error.Message}");
    Console.Error.WriteLine($"Request ID: {ex.RequestId}");
}
```

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

### Build Documentation Site

Source: https://github.com/opensandbox-group/opensandbox/blob/main/docs/README.md

Installs dependencies and builds the production-ready documentation site for OpenSandbox.

```bash
nvm use 22
cd docs
pnpm install
pnpm docs:build
```

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

### FileTenantProvider Configuration (Pseudocode)

Source: https://github.com/opensandbox-group/opensandbox/blob/main/oseps/0012-multi-tenancy.md

Illustrates how the FileTenantProvider is wired during server startup, including fallback to single-tenant mode if the configuration file is absent.

```pseudocode
if tenants.toml exists:
    provider = FileTenantProvider(path)
    if not provider.ready():
        → SystemExit (parse error, duplicates, etc.)
else:
    provider = None  # single-tenant mode
```

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

### Retrieve Sandbox Endpoints

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/sandbox/javascript/README.md

Explains how to get a sandbox endpoint with and without a scheme, providing examples for both `getEndpoint()` and `getEndpointUrl()`.

```typescript
const { endpoint } = await sandbox.getEndpoint(44772);
const url = await sandbox.getEndpointUrl(44772);
```

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

### Initialize Server Configuration

Source: https://github.com/opensandbox-group/opensandbox/blob/main/server/README.md

Generate a starter TOML configuration file for the OpenSandbox server. Use the --example flag to specify the desired runtime environment (e.g., docker, k8s).

```bash
opensandbox-server init-config ~/.sandbox.toml --example docker
```

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

### Get Task Status using curl

Source: https://github.com/opensandbox-group/opensandbox/blob/main/kubernetes/examples/task-executor/README.md

Example of how to retrieve the status of a specific task by its name using curl.

```bash
curl http://localhost:5758/tasks/my-first-task
```

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

### Configure Local Development Environment

Source: https://github.com/opensandbox-group/opensandbox/blob/main/server/DEVELOPMENT.md

Copy the example configuration file and edit it for local development settings, including server host, port, API key, logging level, and runtime configuration.

```bash
cp opensandbox_server/examples/example.config.toml ~/.sandbox.toml
```

```toml
[server]
host = "0.0.0.0"
port = 8080
api_key = "your-secret-api-key-change-this"

[log]
level = "DEBUG"

[runtime]
type = "docker"
execd_image = "opensandbox/execd:v1.0.19"

[docker]
network_mode = "host"
```

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

### Run Controller Example Program

Source: https://github.com/opensandbox-group/opensandbox/blob/main/kubernetes/examples/controller/README.md

Executes the controller example program. It can use the default kubeconfig or a specified path.

```bash
# Use default kubeconfig (~/.kube/config)
go run examples/controller/main.go

# Or specify kubeconfig path
go run examples/controller/main.go -kubeconfig=/path/to/kubeconfig
```

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

### Customize OpenSandbox Controller Installation with --set Flags

Source: https://github.com/opensandbox-group/opensandbox/blob/main/kubernetes/README.md

Customize the OpenSandbox Controller installation by setting specific configuration values using the --set flag. This example demonstrates setting replica count, resource limits, and log level.

```sh
# Example: Custom resource limits
helm install opensandbox-controller \
  https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.1.0/opensandbox-controller-0.1.0.tgz \
  --namespace opensandbox-system \
  --create-namespace \
  --set controller.replicaCount=2 \
  --set controller.resources.limits.cpu=1000m \
  --set controller.resources.limits.memory=512Mi

# Example: Custom log level
helm install opensandbox-controller \
  https://github.com/alibaba/OpenSandbox/releases/download/helm/opensandbox-controller/0.1.0/opensandbox-controller-0.1.0.tgz \
  --namespace opensandbox-system \
  --create-namespace \
  --set controller.logLevel=debug
```

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

### Server Setup and Focused Checks

Source: https://github.com/opensandbox-group/opensandbox/blob/main/server/AGENTS.md

Commands to set up the server environment, run linters, and execute specific integration tests for Docker and schema validation.

```bash
cd server
uv sync --all-groups
uv run ruff check
uv run pytest tests/test_docker_service.py
uv run pytest tests/test_schema.py
```

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

### Basic Sandbox Triage Commands

Source: https://github.com/opensandbox-group/opensandbox/blob/main/cli/src/opensandbox_cli/skills/opensandbox-sandbox-troubleshooting.md

Use these commands to get a quick overview of the sandbox state and health. They are the starting point for most troubleshooting scenarios.

```bash
osb sandbox get <sandbox-id> -o json
osb sandbox health <sandbox-id> -o json
osb diagnostics events <sandbox-id> --scope lifecycle -o raw
osb diagnostics events <sandbox-id> --scope runtime -o raw
osb diagnostics logs <sandbox-id> --scope container -o raw
```

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

### Release Note for execd Path Change

Source: https://github.com/opensandbox-group/opensandbox/blob/main/docs/execd-path-migration.md

This markdown snippet is an example of how to communicate the breaking change regarding the execd installation path in release notes.

```markdown
### Breaking: execd install path flattened

execd and bootstrap.sh are now installed to `/opt/opensandbox/` instead of
`/opt/opensandbox/bin/`. code-interpreter image users must upgrade to `>=v1.1.0`.
Custom Pool CR templates and custom execd images require updates.

See [execd Path Migration Guide](docs/execd-path-migration.md) for full details.
```

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

### Run Host Volume Mount Example

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/host-volume-mount/README.md

Execute the Python script that demonstrates host volume mounting. Ensure the HOST_VOLUME_PATH environment variable is set.

```shell
HOST_VOLUME_PATH=/tmp/opensandbox-data uv run python examples/host-volume-mount/main.py
```

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

### Mount Host Volume (JavaScript/TypeScript)

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/host-volume-mount/README.md

This example shows how to configure a host volume mount for sandbox creation using the JavaScript/TypeScript SDK. Ensure the '@alibaba-group/opensandbox' package is installed.

```typescript
import { Sandbox } from "@alibaba-group/opensandbox";

const sandbox = await Sandbox.create({
  image: "ubuntu",
  volumes: [
    {
      name: "my-data",
      host: { path: "/data/shared" },
      mountPath: "/mnt/data",
      readOnly: false,
    },
  ],
});
```

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

### Quick Start: Execute Python Code

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/code-interpreter/javascript/README.md

Demonstrates creating a sandbox, setting up the Code Interpreter, executing a Python script to print its version and a simple calculation, and then cleaning up the sandbox. Ensure the OpenSandbox service is running before execution.

```typescript
import { ConnectionConfig, Sandbox } from "@alibaba-group/opensandbox";
import { CodeInterpreter, SupportedLanguages } from "@alibaba-group/opensandbox-code-interpreter";

// 1. Configure connection
const config = new ConnectionConfig({
  domain: "api.opensandbox.io",
  apiKey: "your-api-key",
});

// 2. Create a Sandbox with the code-interpreter image + runtime versions
const sandbox = await Sandbox.create({
  connectionConfig: config,
  image: "opensandbox/code-interpreter:v1.1.0",
  entrypoint: ["/opt/code-interpreter/code-interpreter.sh"],
  env: {
    PYTHON_VERSION: "3.11",
    JAVA_VERSION: "17",
    NODE_VERSION: "20",
    GO_VERSION: "1.24",
  },
  timeoutSeconds: 15 * 60,
});

// 3. Create CodeInterpreter wrapper
const ci = await CodeInterpreter.create(sandbox);

// 4. Create an execution context (Python)
const ctx = await ci.codes.createContext(SupportedLanguages.PYTHON);

// 5. Run code
const result = await ci.codes.run("import sys\nprint(sys.version)\nresult = 2 + 2\nresult", {
  context: ctx,
});

// 6. Print output
console.log(result.result[0]?.text);

// 7. Cleanup remote instance (optional but recommended)
await sandbox.kill();
await sandbox.close();

```

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

### Kubernetes InitContainer for Log Directory Setup

Source: https://github.com/opensandbox-group/opensandbox/blob/main/kubernetes/docs/logging.md

Configures an initContainer within Kubernetes to create and set permissions for a log directory. This ensures the directory is ready before the main container starts.

```yaml
spec:
  initContainers:
  - name: setup-log-dir
    image: busybox
    command: ['sh', '-c', 'mkdir -p /var/log/controller && chmod 755 /var/log/controller']
    volumeMounts:
    - name: log-volume
      mountPath: /var/log/controller
  containers:
  - name: controller
    securityContext:
      runAsUser: 1000
      runAsGroup: 1000
```

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

### Install Project Dependencies with uv

Source: https://github.com/opensandbox-group/opensandbox/blob/main/server/DEVELOPMENT.md

Install all necessary project dependencies using the 'uv sync' command.

```bash
uv sync
```

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

### Create and Access VS Code Sandbox

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/vscode/README.md

Installs the OpenSandbox package and runs a Python script to start a VS Code sandbox. The script disables authentication and outputs the accessible address.

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

uv run python examples/vscode/main.py

```

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

### Example Structured Event Log Entries

Source: https://github.com/opensandbox-group/opensandbox/blob/main/components/internal/supervisor/README.md

These JSONL records represent various lifecycle events of a worker process managed by the supervisor. They include start, exit, backoff, and prestart events.

```jsonl
{"ts":"2026-01-15T10:30:00Z","name":"egress","event":"start","pid":42,"gen":1,"attempt":1}
{"ts":"2026-01-15T10:30:00.15Z","name":"egress","event":"exit","pid":42,"gen":1,"attempt":1,"exit_code":1,"duration_ms":150,"reason":"crashed"}
{"ts":"2026-01-15T10:30:00.15Z","name":"egress","event":"backoff","sleep_ms":1000,"next_attempt":2}
{"ts":"2026-01-15T10:30:01.15Z","name":"egress","event":"prestart","hook":"cleanup.sh","exit_code":0,"duration_ms":50}
{"ts":"2026-01-15T10:30:01.2Z","name":"egress","event":"start","pid":43,"gen":2,"attempt":2}
```

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

### Create and Use SandboxPool

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/sandbox/kotlin/README.md

Demonstrates how to build, start, acquire, use, and shut down a SandboxPool. Ensure necessary imports are present. The pool manages idle sandboxes for faster acquisition.

```java
import com.alibaba.opensandbox.sandbox.pool.SandboxPool;
import com.alibaba.opensandbox.sandbox.domain.pool.PoolCreationSpec;
import com.alibaba.opensandbox.sandbox.domain.pool.AcquirePolicy;
import com.alibaba.opensandbox.sandbox.infrastructure.pool.InMemoryPoolStateStore;

SandboxPool pool = SandboxPool.builder()
    .poolName("demo-pool")
    .ownerId("worker-1")
    .maxIdle(3)
    .warmupReadyTimeout(Duration.ofSeconds(45))
    .stateStore(new InMemoryPoolStateStore()) // single-node store
    .connectionConfig(config)
    .creationSpec(
        PoolCreationSpec.builder()
            .image("ubuntu:22.04")
            .entrypoint(java.util.List.of("tail", "-f", "/dev/null"))
            .extension("storage.id", "dataset-001")
            .build()
    )
    .build();

pool.start();
Sandbox sb = pool.acquire(Duration.ofMinutes(10), AcquirePolicy.FAIL_FAST);
try {
    sb.commands().run("echo pool-ok");
} finally {
    sb.kill();
    sb.close();
}
pool.shutdown(true);
```

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

### Python SDK Example for PVC Mount

Source: https://github.com/opensandbox-group/opensandbox/blob/main/oseps/0003-volume-and-volumebinding-support.md

Demonstrates how to create a sandbox with a PVC-backed volume using the OpenSandbox Python SDK. This includes setting up the client, resource limits, and the sandbox request with volume configuration.

```python
from opensandbox.api.lifecycle.client import AuthenticatedClient
from opensandbox.api.lifecycle.api.sandboxes import post_sandboxes
from opensandbox.api.lifecycle.models.create_sandbox_request import CreateSandboxRequest
from opensandbox.api.lifecycle.models.image_spec import ImageSpec
from opensandbox.api.lifecycle.models.resource_limits import ResourceLimits
from opensandbox.api.lifecycle.models.volume import Volume
from opensandbox.api.lifecycle.models.pvc import PVC

client = AuthenticatedClient(base_url="https://api.opensandbox.io", token="YOUR_API_KEY")

resource_limits = ResourceLimits.from_dict({"cpu": "500m", "memory": "512Mi"})
request = CreateSandboxRequest(
    image=ImageSpec(uri="python:3.11"),
    timeout=3600,
    resource_limits=resource_limits,
    entrypoint=["python", "-c", "print('hello')"],
    volumes=[
        Volume(
            name="shared-data",
            pvc=PVC(
                claim_name="my-shared-volume",
            ),
            mount_path="/mnt/data",
            sub_path="task-001",
        )
    ],
)

post_sandboxes.sync(client=client, body=request)
```

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

### Execute Codex Command

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/codex-cli/README.md

An example of executing a Codex command using the CLI. This command computes '1+1' and returns the result and reasoning in JSON format. It requires Node.js to be installed and authentication via OPENAI_API_KEY.

```shell
codex exec "Compute 1+1 and return JSON with keys result and reasoning." --skip-git-repo-check
```

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

### Synchronous Quick Start: Create Sandbox and Run Command

Source: https://github.com/opensandbox-group/opensandbox/blob/main/sdks/sandbox/python/README.md

Provides a synchronous alternative for creating a sandbox, executing a shell command, printing its output, and explicitly killing the sandbox. Includes custom HTTP transport and timeout configurations.

```python
from datetime import timedelta

import httpx
from opensandbox import SandboxSync
from opensandbox.config import ConnectionConfigSync

config = ConnectionConfigSync(
    domain="api.opensandbox.io",
    api_key="your-api-key",
    request_timeout=timedelta(seconds=30),
    transport=httpx.HTTPTransport(limits=httpx.Limits(max_connections=20)),
)

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

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

### Create and Access Desktop Sandbox

Source: https://github.com/opensandbox-group/opensandbox/blob/main/examples/desktop/README.md

Installs the OpenSandbox package and runs a Python script to start the desktop stack (Xvfb + XFCE + x11vnc) and launch noVNC/websockify. The script outputs VNC and noVNC access details.

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

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

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

### Troubleshoot Controller Startup Issues

Source: https://github.com/opensandbox-group/opensandbox/blob/main/kubernetes/docs/HELM-DEPLOYMENT.md

Examine pod status, logs, and RBAC permissions when the controller fails to start.

```bash
# View Pod status
kubectl describe pod -n opensandbox-system -l control-plane=controller-manager

# View logs
kubectl logs -n opensandbox-system -l control-plane=controller-manager

# Check RBAC permissions
kubectl auth can-i --as=system:serviceaccount:opensandbox-system:opensandbox-opensandbox-controller-controller-manager create pods
```

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

### Create and Verify Sandbox Readiness

Source: https://github.com/opensandbox-group/opensandbox/blob/main/cli/src/opensandbox_cli/skills/opensandbox-sandbox-lifecycle.md

Create a sandbox with a specified image and timeout, then verify its readiness using get and health commands.

```bash
osb sandbox create --image python:3.12 --timeout 30m -o json
osb sandbox get <sandbox-id> -o json
osb sandbox health <sandbox-id> -o json
```

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

### Install OpenSandbox Server

Source: https://github.com/opensandbox-group/opensandbox/blob/main/server/README.md

Install the OpenSandbox server package using uv pip. This is the recommended method for general installation.

```bash
uv pip install opensandbox-server
```