roche-sandbox 0.1.0

Universal sandbox orchestrator for AI agents — Python SDK

roche-sandbox

Python SDK for Roche -- universal sandbox orchestrator for AI agents.

Requirements

• Python >= 3.10
• Roche CLI on PATH (or Roche daemon running)

Install

pip install roche-sandbox

Quick Start

from roche_sandbox import Roche

roche = Roche()
sandbox = roche.create(image="python:3.12-slim")
output = sandbox.exec(["python3", "-c", "print('Hello from Roche!')"])
print(output.stdout)  # Hello from Roche!
sandbox.destroy()

Context Manager (auto-cleanup)

with roche.create(image="python:3.12-slim") as sandbox:
    output = sandbox.exec(["echo", "hello"])

Async API

import asyncio
from roche_sandbox import AsyncRoche

async def main():
    roche = AsyncRoche()
    sandbox = await roche.create(image="python:3.12-slim")
    output = await sandbox.exec(["echo", "hello"])
    await sandbox.destroy()

asyncio.run(main())

Configuration

sandbox = roche.create(
    image="python:3.12-slim",
    memory="512m",
    cpus=1.0,
    timeout_secs=600,
    network=False,    # default: AI-safe
    writable=False,   # default: AI-safe
    env={"API_KEY": "secret"},
)

Transport

The SDK auto-detects whether the Roche gRPC daemon is running and connects to it. If the daemon is unavailable, it falls back to invoking the Roche CLI as a subprocess.

You can force CLI mode explicitly:

roche = Roche(mode="direct")

API Styles

The SDK provides two API styles:

• Async-first: AsyncRoche and AsyncSandbox -- native async/await support.
• Sync wrapper: Roche and Sandbox -- blocking equivalents for scripts and notebooks.

Public Exports

from roche_sandbox import (
    Roche, AsyncRoche,
    Sandbox, AsyncSandbox,
    SandboxConfig, ExecOutput, SandboxInfo,
    Mount, SandboxStatus,
    RocheError, SandboxNotFound, SandboxPaused,
    ProviderUnavailable, TimeoutError, UnsupportedOperation,
)

License

Apache-2.0 -- see LICENSE.