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 # SDK only (requires Roche CLI installed separately)
pip install roche-sandbox[cli] # SDK + auto-download prebuilt CLI binary
If you installed without [cli], you can download the CLI later:
roche-install-cli # downloads from GitHub Releases
cargo install roche-cli # or build from source
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:
AsyncRocheandAsyncSandbox-- nativeasync/awaitsupport. - Sync wrapper:
RocheandSandbox-- blocking equivalents for scripts and notebooks.
Public Exports
from roche_sandbox import (
Roche, AsyncRoche,
Sandbox, AsyncSandbox,
roche_sandbox, # decorator
SandboxConfig, ExecOutput, SandboxInfo,
Mount, SandboxStatus,
RocheError, SandboxNotFound, SandboxPaused,
ProviderUnavailable, TimeoutError, UnsupportedOperation,
)
@roche_sandbox Decorator
The decorator automatically creates and injects a sandbox into your function — no manual lifecycle management needed. Works with both sync and async functions.
from roche_sandbox import roche_sandbox
@roche_sandbox(image="python:3.12-slim")
def run_code(code: str, sandbox) -> str:
result = sandbox.exec(["python3", "-c", code])
return result.stdout
output = run_code("print('hello')") # sandbox is auto-managed
Async
@roche_sandbox(image="python:3.12-slim")
async def run_code(code: str, sandbox) -> str:
result = await sandbox.exec(["python3", "-c", code])
return result.stdout
Agent Framework Integration
The decorator strips the sandbox parameter from the function signature, so agent frameworks (OpenAI, LangChain, CrewAI, etc.) only see user-facing parameters:
from agents import function_tool
@function_tool
@roche_sandbox(image="python:3.12-slim")
def run_code(code: str, sandbox) -> str:
"""Execute Python code in a sandbox."""
return sandbox.exec(["python3", "-c", code]).stdout
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
image |
str |
"python:3.12-slim" |
Container image |
provider |
str |
"docker" |
Sandbox provider |
network |
bool |
False |
Enable network access |
writable |
bool |
False |
Enable writable filesystem |
timeout_secs |
int |
300 |
Sandbox timeout |
memory |
str | None |
None |
Memory limit (e.g. "512m") |
cpus |
float | None |
None |
CPU limit |
sandbox_param |
str |
"sandbox" |
Name of the injected parameter |
Agent Framework Examples
See examples/python/ for integration examples with:
- OpenAI Agents SDK —
@function_toolintegration - LangChain / LangGraph — custom
BaseTool+ stateful retry workflow - CrewAI —
@tooldecorator + multi-agent crew - Anthropic API —
tool_use+ multi-turn agentic loop - AutoGen — custom
CodeExecutor+ group chat - Camel-AI —
BaseToolkit+ role-playing session
All examples run without API keys (simulated mode) and optionally switch to real LLM calls.
License
Apache-2.0 -- see LICENSE.
Metadata
Release files for roche-sandbox 0.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| roche_sandbox-0.6.0.tar.gz | 41.6 kB | Without provenance | Details for roche_sandbox-0.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| roche_sandbox-0.6.0-py3-none-any.whl | Python 3 | none | any | Details for roche_sandbox-0.6.0-py3-none-any.whl |
Total release size: 85.5 kB
Release files / roche_sandbox-0.6.0.tar.gz
| Download URL | roche_sandbox-0.6.0.tar.gz |
|---|---|
| Size | 41.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6fde3aea8b82fe2eba6722a5d550f1095917a72dd6ecd2d9cbf1b9f848e74e18
|
|
BLAKE2b-256 checksum How to use checksums |
e7c7a12fed4e4a4bfaa91d730ca93cb2e9e98c684970bc46c328d7d715befb05
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / roche_sandbox-0.6.0-py3-none-any.whl
| Download URL | roche_sandbox-0.6.0-py3-none-any.whl |
|---|---|
| Size | 43.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f8843f334263625518f217221143895db74ccbd6fc0037371fbedd227935729a
|
|
BLAKE2b-256 checksum How to use checksums |
db3a0b34e943830a2c59f6c8391f04135114a88a87d2622bc09c8c8fcd66f8ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for roche-sandbox 0.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.