# Rust SDK Reference

Complete reference documentation for the microsandbox Rust SDK.

# Installation

cargo add microsandbox

# Quick Start

use microsandbox::{PythonSandbox, SandboxOptions};
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
    let mut sb = PythonSandbox::create("my-sandbox").await?;
    sb.start(None).await?;

    let exec = sb.run("print('Hello, World!')").await?;
    println!("{}", exec.output().await?);

    sb.stop().await?;
    Ok(())
}

# PythonSandbox

The main struct for creating and managing Python execution environments.

PythonSandbox::create(name: &str) -> Result<Self, Box<dyn Error + Send + Sync>>
PythonSandbox::create_with_options(options: SandboxOptions) -> Result<Self, Box<dyn Error + Send + Sync>>

Parameter	Type	Description
`name`	`&str`	Sandbox identifier
`options`	`SandboxOptions`	Configuration options for the sandbox

// Simple creation with name
let sb = PythonSandbox::create("my-sandbox").await?;

// Creation with options
let options = SandboxOptions::builder()
    .name("my-sandbox")
    .namespace("default")
    .server_url("http://127.0.0.1:5555")
    .api_key("my-key")
    .build();
let sb = PythonSandbox::create_with_options(options).await?;

# Instance Methods

Starts the sandbox with optional resource constraints.

async fn start(
    &mut self,
    options: Option<StartOptions>
) -> Result<(), Box<dyn Error + Send + Sync>>

Parameter	Type	Description
`options`	`StartOptions`	Optional configuration for sandbox startup

// Start with defaults
sb.start(None).await?;

// Start with custom options
let options = StartOptions {
    image: Some("microsandbox/python".to_string()),
    memory: 1024,
    cpus: 2.0,
    timeout: 180.0,
};
sb.start(Some(options)).await?;

Stops and cleans up the sandbox.

async fn stop(&mut self) -> Result<(), Box<dyn Error + Send + Sync>>

Executes Python code in the sandbox environment.

async fn run(
    &self,
    code: &str
) -> Result<Execution, Box<dyn Error + Send + Sync>>

Parameter	Type	Description
`code`	`&str`	Python code to execute

Returns: Execution object with results

let exec = sb.run("print('Hello, World!')").await?;
println!("{}", exec.output().await?);

let code = r#"
import math
result = math.sqrt(16)
print(f"Square root of 16 is: {result}")
"#;
let exec = sb.run(code).await?;

# Methods

Access to shell command execution interface.

async fn command(&self) -> Result<Command, Box<dyn Error + Send + Sync>>

let cmd = sb.command().await?;
let result = cmd.run("ls", Some(vec!["-la", "/"]), None).await?;
println!("{}", result.output().await?);

Access to resource monitoring interface.

async fn metrics(&self) -> Result<Metrics, Box<dyn Error + Send + Sync>>

let metrics = sb.metrics().await?;
let cpu = metrics.cpu().await?;
let memory = metrics.memory().await?;
println!("CPU: {}%, Memory: {} MiB", cpu.unwrap_or(0.0), memory.unwrap_or(0));

# NodeSandbox

JavaScript/Node.js execution environment with identical API to PythonSandbox.

NodeSandbox::create(name: &str) -> Result<Self, Box<dyn Error + Send + Sync>>
NodeSandbox::create_with_options(options: SandboxOptions) -> Result<Self, Box<dyn Error + Send + Sync>>

Parameter	Type	Description
`name`	`&str`	Sandbox identifier
`options`	`SandboxOptions`	Configuration options for the sandbox

All methods are identical to PythonSandbox but execute JavaScript code.

use microsandbox::NodeSandbox;

let mut sb = NodeSandbox::create("js-sandbox").await?;
sb.start(None).await?;

let exec = sb.run("console.log('Hello from Node.js!');").await?;
println!("{}", exec.output().await?);

sb.stop().await?;

# Execution

Represents the result of code execution from sandbox.run().

# Methods

Returns standard output from execution.

async fn output(&self) -> Result<String, Box<dyn Error + Send + Sync>>

Returns standard error from execution.

async fn error(&self) -> Result<String, Box<dyn Error + Send + Sync>>

Checks if execution produced errors.

fn has_error(&self) -> bool

Example: Handling Execution Results

let exec = sb.run("print('Hello'); import sys; sys.exit(1)").await?;
println!("Has error: {}", exec.has_error());
println!("Output: {}", exec.output().await?);
if exec.has_error() {
    println!("Error: {}", exec.error().await?);
}

# CommandExecution

Represents the result of command execution from sandbox.command.run().

# Methods

Returns standard output from command execution.

async fn output(&self) -> Result<String, Box<dyn Error + Send + Sync>>

Returns standard error from command execution.

async fn error(&self) -> Result<String, Box<dyn Error + Send + Sync>>

Command exit code.

fn exit_code(&self) -> i32

True if command was successful (exit code 0).

fn success(&self) -> bool

# Command

Interface for executing shell commands within sandboxes.

Executes shell commands with arguments.

async fn run(
    &self,
    command: &str,
    args: Option<Vec<&str>>,
    timeout: Option<u32>
) -> Result<CommandExecution, Box<dyn Error + Send + Sync>>

Parameter	Type	Description
`command`	`&str`	Command to execute
`args`	`Option<Vec<&str>>`	Command arguments (optional)
`timeout`	`Option<u32>`	Execution timeout in seconds (optional)

Returns: CommandExecution object with results

let result = cmd.run("ls", None, None).await?;

let result = cmd.run("ls", Some(vec!["-la", "/tmp"]), None).await?;

let result = cmd.run("sleep", Some(vec!["10"]), Some(5)).await?;

let result = cmd.run("ls", Some(vec!["/nonexistent"]), None).await?;
if result.success() {
    println!("Output: {}", result.output().await?);
} else {
    println!("Error: {}", result.error().await?);
    println!("Exit code: {}", result.exit_code());
}

# Metrics

Interface for monitoring sandbox resource usage and performance.

# Methods

Current CPU usage percentage.

async fn cpu(&self) -> Result<Option<f32>, Box<dyn Error + Send + Sync>>

Current memory usage in MiB.

async fn memory(&self) -> Result<Option<u64>, Box<dyn Error + Send + Sync>>

Current disk usage in bytes.

async fn disk(&self) -> Result<Option<u64>, Box<dyn Error + Send + Sync>>

Sandbox running status.

async fn is_running(&self) -> Result<bool, Box<dyn Error + Send + Sync>>

All metrics as a JSON value.

async fn all(&self) -> Result<serde_json::Value, Box<dyn Error + Send + Sync>>

Returns: JSON object with keys: name, namespace, running, cpu_usage, memory_usage, disk_usage

// Individual metrics
let metrics = sb.metrics().await?;
let cpu = metrics.cpu().await?;
let memory = metrics.memory().await?;
let disk = metrics.disk().await?;
let running = metrics.is_running().await?;

println!("CPU: {}%", cpu.unwrap_or(0.0));
println!("Memory: {} MiB", memory.unwrap_or(0));
println!("Disk: {} bytes", disk.unwrap_or(0));
println!("Running: {}", running);

// All metrics at once
let all_metrics = metrics.all().await?;
println!("All metrics: {}", all_metrics);

# Configuration

# Environment Variables

Variable	Description
`MSB_API_KEY`	API key for authentication
`MSB_SERVER_URL`	Default server URL (overrides default)

# Server Configuration

Default server URL: http://127.0.0.1:5555

# Error Handling

Common Error Types

The SDK provides a SandboxError enum for various conditions:

NotStarted — Attempting operations on stopped sandboxes
RequestFailed — Server unreachable or network issues
ServerError — Server-side errors
Timeout — Operations exceed time limits
HttpError — Network-related errors
InvalidResponse — Malformed server responses

# Best Practices

use microsandbox::{PythonSandbox, SandboxError};

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
    let mut sb = PythonSandbox::create("error-test").await?;

    match sb.start(None).await {
        Ok(_) => {
            let exec = sb.run("potentially_failing_code()").await?;
            if exec.has_error() {
                println!("Execution error: {}", exec.error().await?);
            } else {
                println!("Success: {}", exec.output().await?);
            }
            sb.stop().await?;
        }
        Err(e) => {
            if let Some(sandbox_err) = e.downcast_ref::<SandboxError>() {
                println!("Sandbox error: {}", sandbox_err);
            } else {
                println!("Unknown error: {}", e);
            }
        }
    }
    Ok(())
}

# Best Practices

Recommended Practices

Use Result types — Handle all potential errors
Set appropriate timeouts — Prevent hanging operations
Handle errors gracefully — Match on error types
Monitor resources — Use metrics interface
Use meaningful names — Easier debugging and management
Install packages once — Reuse sandbox for multiple executions
Always call stop() — Prevent resource leaks

Common Pitfalls

Forgetting to call stop() after sandbox usage
Not handling all potential error cases
Setting timeouts too low for complex operations
Creating too many concurrent sandboxes without resource limits

references