adk-sandbox

Isolated code execution runtime for ADK-Rust agents.

adk-sandbox provides the SandboxBackend trait and two implementations for executing code in isolation. It separates the isolation concern from language-specific toolchains — adk-code handles compilation and language pipelines, while adk-sandbox handles running the resulting code safely.

Feature Flags

Backend Comparison

ProcessBackend is honest about what it does not enforce. Use WasmBackend when you need full sandboxing with memory limits and no host access.

Quick Start

use adk_sandbox::{ProcessBackend, ExecRequest, Language, SandboxBackend};
use std::time::Duration;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let backend = ProcessBackend::default();

    let mut env = HashMap::new();
    env.insert("PATH".to_string(), std::env::var("PATH").unwrap_or_default());

    let request = ExecRequest {
        language: Language::Python,
        code: "print('hello from sandbox')".to_string(),
        stdin: None,
        timeout: Duration::from_secs(30),
        memory_limit_mb: None,
        env,
    };

    let result = backend.execute(request).await?;
    println!("stdout: {}", result.stdout);
    println!("exit_code: {}", result.exit_code);
    Ok(())
}

Note: ExecRequest has no Default implementation — timeout must always be set explicitly.

SandboxTool (Agent Integration)

SandboxTool implements adk_core::Tool, making sandbox execution available to LLM agents. Errors are returned as structured JSON (never as ToolError), so the agent can reason about failures.

use adk_sandbox::{SandboxTool, ProcessBackend};
use std::sync::Arc;

let backend = Arc::new(ProcessBackend::default());
let tool = SandboxTool::new(backend);

// Use with any LLM agent
let agent = LlmAgentBuilder::new("sandbox_agent")
    .tool(Arc::new(tool))
    .build()?;

The tool accepts language, code, optional stdin, and optional timeout_secs parameters. It requires the code:execute scope.

Error Handling

All backend errors use SandboxError:

Non-zero exit codes are not errors — they are returned in ExecResult.exit_code.

OS Sandbox Profiles

OS-level sandbox enforcement restricts child processes at the kernel level — blocking network access, limiting filesystem writes, and controlling process spawning. This goes beyond ProcessBackend's default environment isolation.

Feature Flags

Usage

use adk_sandbox::{
    ProcessBackend, ProcessConfig, SandboxBackend,
    SandboxPolicyBuilder, get_enforcer,
};

// 1. Build a policy
let policy = SandboxPolicyBuilder::new()
    .allow_read("/usr")
    .allow_read("/tmp")
    .allow_read_write("/tmp/work")
    .allow_process_spawn()
    // Network is denied by default
    .env("PATH", "/usr/bin:/usr/local/bin")
    .build();

// 2. Get the platform enforcer
let enforcer = get_enforcer()?;
println!("Using enforcer: {}", enforcer.name());

// 3. Create a sandboxed backend
let backend = ProcessBackend::with_sandbox(
    ProcessConfig::default(),
    enforcer,
    policy,
);

// 4. Execute code — network is blocked, writes restricted
let result = backend.execute(request).await?;

Platform Differences

Example

See examples/sandbox_agent/ for a full LLM-agent-driven example that executes Python code in a sandboxed environment with network access blocked.

License

Apache-2.0