Struct Sandbox 

pub struct Sandbox { /* private fields */ }

Active sandbox

Implementations

impl Sandbox

pub fn id(&self) -> &str

Get sandbox ID

Examples found in repository

examples/basic.rs (line 18)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Sandbox RS - Basic Example ===\n");

    // Create a sandbox with basic configuration
    println!("[1] Creating sandbox with memory limit...");
    let mut sandbox = SandboxBuilder::new("example-1")
        .memory_limit(50 * 1024 * 1024) // 50MB
        .cpu_limit_percent(50) // 50% of one CPU
        .timeout(Duration::from_secs(5))
        .seccomp_profile(SeccompProfile::Minimal)
        .build()?;

    println!("[*] Sandbox created: {}", sandbox.id());
    println!("[*] Root: {}", sandbox.root().display());
    println!(
        "[*] Status: {}\n",
        if sandbox.is_running() {
            "running"
        } else {
            "idle"
        }
    );

    // Try to run a simple command
    println!("[2] Running 'echo hello' in sandbox...");
    let result = sandbox.run("/bin/echo", &["hello", "world"])?;

    println!("[*] Execution result:");
    println!("Exit code: {}", result.exit_code);
    println!("Wall time: {} ms", result.wall_time_ms);
    println!("Memory peak: {} bytes", result.memory_peak);
    println!("CPU time: {} μs", result.cpu_time_us);
    println!("Timed out: {}\n", result.timed_out);

    Ok(())
}

examples/cgroup_limits.rs (line 15)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Sandbox RS - Cgroup Resource Limits ===\n");

    // Example 1: Memory limited sandbox
    println!("[1] Example: Memory-limited sandbox (100MB)");
    let sandbox1 = SandboxBuilder::new("mem-limited")
        .memory_limit_str("100M")?
        .cpu_limit_percent(100)
        .build()?;
    println!("[*] Created: {}", sandbox1.id());
    println!("[*] Root: {}\n", sandbox1.root().display());

    // Example 2: CPU limited sandbox
    println!("[2] Example: CPU-limited sandbox (25% of one core)");
    let sandbox2 = SandboxBuilder::new("cpu-limited")
        .cpu_limit_percent(25)
        .memory_limit(512 * 1024 * 1024) // 512MB
        .timeout(Duration::from_secs(10))
        .build()?;
    println!("[*] Created: {}", sandbox2.id());
    println!("[*] Root: {}\n", sandbox2.root().display());

    // Example 3: Tight limits for untrusted code
    println!("[3] Example: Tight limits for untrusted code");
    let sandbox3 = SandboxBuilder::new("untrusted")
        .memory_limit_str("64M")?
        .cpu_limit_percent(10)
        .max_pids(8)
        .timeout(Duration::from_secs(5))
        .seccomp_profile(sandbox_rs::SeccompProfile::Minimal)
        .build()?;
    println!("[*] Created: {}", sandbox3.id());
    println!("[*] Root: {}\n", sandbox3.root().display());

    println!("[*] All sandboxes created successfully!");
    println!("[*] Note: Actual resource enforcement requires root permissions");

    Ok(())
}

pub fn root(&self) -> &Path

Get sandbox root

Examples found in repository

examples/basic.rs (line 19)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Sandbox RS - Basic Example ===\n");

    // Create a sandbox with basic configuration
    println!("[1] Creating sandbox with memory limit...");
    let mut sandbox = SandboxBuilder::new("example-1")
        .memory_limit(50 * 1024 * 1024) // 50MB
        .cpu_limit_percent(50) // 50% of one CPU
        .timeout(Duration::from_secs(5))
        .seccomp_profile(SeccompProfile::Minimal)
        .build()?;

    println!("[*] Sandbox created: {}", sandbox.id());
    println!("[*] Root: {}", sandbox.root().display());
    println!(
        "[*] Status: {}\n",
        if sandbox.is_running() {
            "running"
        } else {
            "idle"
        }
    );

    // Try to run a simple command
    println!("[2] Running 'echo hello' in sandbox...");
    let result = sandbox.run("/bin/echo", &["hello", "world"])?;

    println!("[*] Execution result:");
    println!("Exit code: {}", result.exit_code);
    println!("Wall time: {} ms", result.wall_time_ms);
    println!("Memory peak: {} bytes", result.memory_peak);
    println!("CPU time: {} μs", result.cpu_time_us);
    println!("Timed out: {}\n", result.timed_out);

    Ok(())
}

examples/cgroup_limits.rs (line 16)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Sandbox RS - Cgroup Resource Limits ===\n");

    // Example 1: Memory limited sandbox
    println!("[1] Example: Memory-limited sandbox (100MB)");
    let sandbox1 = SandboxBuilder::new("mem-limited")
        .memory_limit_str("100M")?
        .cpu_limit_percent(100)
        .build()?;
    println!("[*] Created: {}", sandbox1.id());
    println!("[*] Root: {}\n", sandbox1.root().display());

    // Example 2: CPU limited sandbox
    println!("[2] Example: CPU-limited sandbox (25% of one core)");
    let sandbox2 = SandboxBuilder::new("cpu-limited")
        .cpu_limit_percent(25)
        .memory_limit(512 * 1024 * 1024) // 512MB
        .timeout(Duration::from_secs(10))
        .build()?;
    println!("[*] Created: {}", sandbox2.id());
    println!("[*] Root: {}\n", sandbox2.root().display());

    // Example 3: Tight limits for untrusted code
    println!("[3] Example: Tight limits for untrusted code");
    let sandbox3 = SandboxBuilder::new("untrusted")
        .memory_limit_str("64M")?
        .cpu_limit_percent(10)
        .max_pids(8)
        .timeout(Duration::from_secs(5))
        .seccomp_profile(sandbox_rs::SeccompProfile::Minimal)
        .build()?;
    println!("[*] Created: {}", sandbox3.id());
    println!("[*] Root: {}\n", sandbox3.root().display());

    println!("[*] All sandboxes created successfully!");
    println!("[*] Note: Actual resource enforcement requires root permissions");

    Ok(())
}

pub fn is_running(&self) -> bool

Check if sandbox is running

Examples found in repository

examples/basic.rs (line 22)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Sandbox RS - Basic Example ===\n");

    // Create a sandbox with basic configuration
    println!("[1] Creating sandbox with memory limit...");
    let mut sandbox = SandboxBuilder::new("example-1")
        .memory_limit(50 * 1024 * 1024) // 50MB
        .cpu_limit_percent(50) // 50% of one CPU
        .timeout(Duration::from_secs(5))
        .seccomp_profile(SeccompProfile::Minimal)
        .build()?;

    println!("[*] Sandbox created: {}", sandbox.id());
    println!("[*] Root: {}", sandbox.root().display());
    println!(
        "[*] Status: {}\n",
        if sandbox.is_running() {
            "running"
        } else {
            "idle"
        }
    );

    // Try to run a simple command
    println!("[2] Running 'echo hello' in sandbox...");
    let result = sandbox.run("/bin/echo", &["hello", "world"])?;

    println!("[*] Execution result:");
    println!("Exit code: {}", result.exit_code);
    println!("Wall time: {} ms", result.wall_time_ms);
    println!("Memory peak: {} bytes", result.memory_peak);
    println!("CPU time: {} μs", result.cpu_time_us);
    println!("Timed out: {}\n", result.timed_out);

    Ok(())
}

pub fn run(&mut self, program: &str, args: &[&str]) -> Result<SandboxResult>

Run program in sandbox

Examples found in repository

examples/basic.rs (line 31)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("=== Sandbox RS - Basic Example ===\n");

    // Create a sandbox with basic configuration
    println!("[1] Creating sandbox with memory limit...");
    let mut sandbox = SandboxBuilder::new("example-1")
        .memory_limit(50 * 1024 * 1024) // 50MB
        .cpu_limit_percent(50) // 50% of one CPU
        .timeout(Duration::from_secs(5))
        .seccomp_profile(SeccompProfile::Minimal)
        .build()?;

    println!("[*] Sandbox created: {}", sandbox.id());
    println!("[*] Root: {}", sandbox.root().display());
    println!(
        "[*] Status: {}\n",
        if sandbox.is_running() {
            "running"
        } else {
            "idle"
        }
    );

    // Try to run a simple command
    println!("[2] Running 'echo hello' in sandbox...");
    let result = sandbox.run("/bin/echo", &["hello", "world"])?;

    println!("[*] Execution result:");
    println!("Exit code: {}", result.exit_code);
    println!("Wall time: {} ms", result.wall_time_ms);
    println!("Memory peak: {} bytes", result.memory_peak);
    println!("CPU time: {} μs", result.cpu_time_us);
    println!("Timed out: {}\n", result.timed_out);

    Ok(())
}

pub fn run_with_stream( &mut self, program: &str, args: &[&str], ) -> Result<(SandboxResult, ProcessStream)>

Run program with streaming output

Examples found in repository

examples/stream_long_running.rs (lines 28-34)

fn main() -> sandbox_rs::Result<()> {
    let tmp = tempdir().expect("Failed to create temp dir");

    let mut sandbox = SandboxBuilder::new("long-running-example")
        .memory_limit_str("512M")?
        .cpu_limit_percent(100)
        .timeout(Duration::from_secs(30))
        .seccomp_profile(SeccompProfile::Unrestricted)
        .root(tmp.path())
        .build()?;

    println!("Running bash script with streaming output...\n");

    // Run a bash script that outputs multiple lines
    let (result, stream) = sandbox.run_with_stream(
        "/bin/bash",
        &[
            "-c",
            "for i in {1..5}; do echo \"Line $i from stdout\"; echo \"Error line $i\" >&2; done",
        ],
    )?;

    println!("Streaming output:");

    let mut stdout_count = 0;
    let mut stderr_count = 0;
    let mut final_exit_code = result.exit_code;

    for chunk in stream.into_iter() {
        match chunk {
            StreamChunk::Stdout(line) => {
                stdout_count += 1;
                println!("  [OUT #{}] {}", stdout_count, line);
            }
            StreamChunk::Stderr(line) => {
                stderr_count += 1;
                eprintln!("  [ERR #{}] {}", stderr_count, line);
            }
            StreamChunk::Exit {
                exit_code,
                signal: _,
            } => {
                println!("Process finished with exit code: {}", exit_code);
                final_exit_code = exit_code;
            }
        }
    }

    let mut result = result;
    result.exit_code = final_exit_code;

    println!("\nSummary:");
    println!("  Stdout lines: {}", stdout_count);
    println!("  Stderr lines: {}", stderr_count);
    println!("  Wall time: {} ms", result.wall_time_ms);
    println!("  Exit code: {}", result.exit_code);

    result.check_seccomp_error()?;

    Ok(())
}

examples/stream_basic.rs (line 25)

fn main() -> sandbox_rs::Result<()> {
    // Create a temporary directory for the sandbox
    let tmp = tempdir().expect("Failed to create temp dir");

    // Create a sandbox with streaming enabled
    let mut sandbox = SandboxBuilder::new("stream-example")
        .memory_limit_str("256M")?
        .cpu_limit_percent(50)
        .timeout(Duration::from_secs(30))
        .root(tmp.path())
        .build()?;

    println!("Starting sandboxed process with streaming...\n");

    // Run process with streaming
    let (result, stream) = sandbox.run_with_stream("/bin/echo", &["Hello from sandbox!"])?;

    println!("Process output (streaming):");

    // Iterate through all output chunks
    let mut final_exit_code = result.exit_code;
    let mut final_signal = result.signal;

    for chunk in stream.into_iter() {
        match chunk {
            StreamChunk::Stdout(line) => {
                println!("[STDOUT] {}", line);
            }
            StreamChunk::Stderr(line) => {
                eprintln!("[STDERR] {}", line);
            }
            StreamChunk::Exit { exit_code, signal } => {
                println!("\nProcess exited with code: {}", exit_code);
                if let Some(sig) = signal {
                    println!("Killed by signal: {}", sig);
                }
                final_exit_code = exit_code;
                final_signal = signal;
            }
        }
    }

    // Update result with the actual exit code from streaming
    let mut result = result;
    result.exit_code = final_exit_code;
    result.signal = final_signal;

    println!("\nExecution stats:");
    println!("  Exit code: {}", result.exit_code);
    println!("  Wall time: {} ms", result.wall_time_ms);
    println!("  Memory peak: {} bytes", result.memory_peak);

    // Check for seccomp errors and return error if found
    result.check_seccomp_error()?;

    Ok(())
}

examples/stream_non_blocking.rs (lines 27-33)

fn main() -> sandbox_rs::Result<()> {
    let tmp = tempdir().expect("Failed to create temp dir");

    let mut sandbox = SandboxBuilder::new("non-blocking-example")
        .memory_limit_str("256M")?
        .cpu_limit_percent(50)
        .seccomp_profile(SeccompProfile::Unrestricted)
        .root(tmp.path())
        .build()?;

    println!("Running process with non-blocking stream reads...\n");

    // Run a process that outputs slowly
    let (result, stream) = sandbox.run_with_stream(
        "/bin/bash",
        &[
            "-c",
            "for i in {1..3}; do echo \"Message $i\"; sleep 0.1; done",
        ],
    )?;

    println!("Non-blocking polling:");

    let mut received_chunks = 0;
    let mut polling_attempts = 0;
    let mut final_exit_code = result.exit_code;

    loop {
        polling_attempts += 1;

        // Try to read without blocking
        match stream.try_recv()? {
            Some(chunk) => match chunk {
                StreamChunk::Stdout(line) => {
                    println!("[STDOUT] {}", line);
                    received_chunks += 1;
                }
                StreamChunk::Stderr(line) => {
                    eprintln!("[STDERR] {}", line);
                    received_chunks += 1;
                }
                StreamChunk::Exit {
                    exit_code,
                    signal: _,
                } => {
                    println!("Process exited with code: {}", exit_code);
                    // Capture the real exit code from the stream
                    final_exit_code = exit_code;
                    break;
                }
            },
            None => {
                // No data available right now, we could do other work here
                std::thread::sleep(Duration::from_millis(10));
            }
        }

        // Safety limit to prevent infinite loop in case of issues
        if polling_attempts > 10000 {
            println!("Safety timeout reached");
            break;
        }
    }

    // Update result with the actual exit code from streaming
    let mut result = result;
    result.exit_code = final_exit_code;

    println!("\nStatistics:");
    println!("  Chunks received: {}", received_chunks);
    println!("  Polling attempts: {}", polling_attempts);
    println!("  Exit code: {}", result.exit_code);
    println!("  Wall time: {} ms", result.wall_time_ms);

    // Check for seccomp errors and return error if found
    result.check_seccomp_error()?;

    Ok(())
}

pub fn kill(&mut self) -> Result<()>

pub fn get_resource_usage(&self) -> Result<(u64, u64)>

Get resource usage

Trait Implementations

impl Drop for Sandbox

fn drop(&mut self)

Executes the destructor for this type.