sandbox.exec

The sandbox.exec tool executes code in a triple-namespace sandbox (new PID, network, and mount namespaces). It supports sh, python3, and node runtimes.

Capability Required

sandbox.exec

Note: This capability does not follow the tool.invoke: prefix convention; it uses sandbox.exec directly.

Input Schema

{
  "type": "object",
  "required": ["runtime", "code"],
  "properties": {
    "runtime": {
      "type": "string",
      "enum": ["sh", "python3", "node"],
      "description": "The runtime to execute the code in."
    },
    "code": {
      "type": "string",
      "description": "The code or script to execute."
    },
    "stdin": {
      "type": "string",
      "description": "Optional data to pipe to stdin."
    },
    "timeout_ms": {
      "type": "integer",
      "minimum": 1,
      "description": "Execution timeout in milliseconds. Default: 5000."
    },
    "secrets": {
      "type": "object",
      "description": "Map of env var name to secret handle. Injected into the sandboxed process environment.",
      "additionalProperties": { "type": "string" }
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "stdout":    { "type": "string",  "description": "Standard output." },
    "stderr":    { "type": "string",  "description": "Standard error." },
    "exit_code": { "type": "integer", "description": "Process exit code." }
  }
}

Examples

#![allow(unused)]
fn main() {
// Shell script
let result = agent.invoke_tool("sandbox.exec", json!({
    "runtime": "sh",
    "code": "echo hello && ls /tmp",
    "timeout_ms": 3000
})).await?;
println!("stdout: {}", result["stdout"]);
println!("exit: {}", result["exit_code"]);

// Python
let result = agent.invoke_tool("sandbox.exec", json!({
    "runtime": "python3",
    "code": "import json\nprint(json.dumps({'sum': 1 + 2}))"
})).await?;

// With stdin
let result = agent.invoke_tool("sandbox.exec", json!({
    "runtime": "python3",
    "code": "import sys\ndata = sys.stdin.read()\nprint(data.upper())",
    "stdin": "hello world"
})).await?;

// With secret as environment variable
let result = agent.invoke_tool("sandbox.exec", json!({
    "runtime": "sh",
    "code": "curl -s -H \"Authorization: Bearer $API_KEY\" https://api.example.com/data",
    "secrets": {
        "API_KEY": "{{secret:my-api-key}}"
    }
})).await?;
}

Sandbox Isolation

The sandboxed process runs in new PID, network, and mount namespaces. It:

• Has no network access by default (new network namespace with no external interface)
• Cannot see the agent's processes
• Gets a minimal read-only filesystem view
• Is killed after timeout_ms milliseconds

Cost

Estimated cost: 1.0

Error Cases