flash-sandbox 0.1.2

A Python SDK for interacting with the Sandbox Orchestrator.

Sandbox SDK

A Python SDK for interacting with the Sandbox Orchestrator. Supports both gRPC and HTTP transports with an identical public interface, so you can swap protocols without changing application logic.

Installation

pip install flash-sandbox

The package pulls in grpcio, protobuf, and requests automatically.

Quick Start

HTTP transport (recommended for simplicity)

from flash_sandbox import HTTPClient

client = HTTPClient(host="localhost", port=8080)

# Start a Docker sandbox
sandbox_id = client.start_sandbox(
    type="docker",
    image="alpine:latest",
    command=["tail", "-f", "/dev/null"],
    memory_mb=128,
    cpu_cores=0.5,
)
print(f"Sandbox ID: {sandbox_id}")

# Execute a command
result = client.exec_command(sandbox_id, ["echo", "Hello from HTTP!"])
print(f"Output: {result.stdout.strip()}")
print(f"Exit code: {result.exit_code}")

# Check status
status = client.get_status(sandbox_id)
print(f"Status: {status}")

# Get resource metrics
metrics = client.get_metrics(sandbox_id)
print(f"Memory: {metrics.memory_usage_bytes} / {metrics.memory_limit_bytes}")
print(f"CPU: {metrics.cpu_percent}%")

# Execute arbitrary Python code
py_out = client.run_python(sandbox_id, "print('Hello Python in Sandbox')")
print(f"Python Output: {py_out.strip()}")

# Get Platform Information
plat_info = client.get_platform_info(sandbox_id)
print(f"Platform Info: {plat_info}")

# Snapshot and resume
snap = client.snapshot_sandbox(sandbox_id)
print(f"Snapshot: {snap['snapshot_path']}")
client.resume_sandbox(sandbox_id)

# Stop
client.stop_sandbox(sandbox_id)
client.close()

Async HTTP transport

import asyncio
from flash_sandbox import AsyncHTTPClient

async def main():
    async with AsyncHTTPClient(host="localhost", port=8080) as client:
        # Start a Docker sandbox
        sandbox_id = await client.start_sandbox(
            type="docker",
            image="alpine:latest",
            command=["tail", "-f", "/dev/null"],
        )
        print(f"Sandbox ID: {sandbox_id}")

        # Execute a command
        result = await client.exec_command(sandbox_id, ["echo", "Hello from Async!"])
        print(f"Output: {result.stdout.strip()}")

        # Stop
        await client.stop_sandbox(sandbox_id)

asyncio.run(main())

gRPC transport

from flash_sandbox import SandboxClient

client = SandboxClient(host="localhost", port=50051)

# Start a Docker sandbox
docker_id = client.start_sandbox(
    type="docker",
    image="alpine:latest",
    command=["tail", "-f", "/dev/null"],
    memory_mb=128,
    cpu_cores=0.5,
)
print(f"Docker Sandbox ID: {docker_id}")

# Start a Firecracker sandbox
fc_id = client.start_sandbox(
    type="firecracker",
    image="alpine:latest",
    command=["tail", "-f", "/dev/null"],
    memory_mb=512,
    cpu_cores=1.0,
)
print(f"Firecracker Sandbox ID: {fc_id}")

# Start a gVisor sandbox
gvisor_id = client.start_sandbox(
    type="gvisor",
    image="alpine:latest",
    command=["tail", "-f", "/dev/null"],
    memory_mb=256,
    cpu_cores=1.0,
)
print(f"gVisor Sandbox ID: {gvisor_id}")

# Check status
status = client.get_status(fc_id)
print(f"Firecracker Status: {status}")

# Snapshot and Resume
snap_res = client.snapshot_sandbox(fc_id)
print(f"Snapshot Data: {snap_res}")
client.resume_sandbox(fc_id)

# Execute commands
exec_res = client.exec_command(gvisor_id, ["echo", "Hello from gVisor!"])
print(f"gVisor Output: {exec_res.stdout.strip()}")
print(f"gVisor Exit Code: {exec_res.exit_code}")

# Stop sandboxes
client.stop_sandbox(docker_id)
client.stop_sandbox(fc_id)
client.stop_sandbox(gvisor_id)
client.close()

API Reference

HTTPClient, AsyncHTTPClient, and SandboxClient expose the same set of methods. AsyncHTTPClient methods must be awaited:

Method	Description
start_sandbox(type, image, command, memory_mb, cpu_cores, ...)	Start a new sandbox and return its ID.
stop_sandbox(sandbox_id)	Stop and remove a running sandbox.
exec_command(sandbox_id, command)	Execute a command in a sandbox. Returns an object with stdout, stderr, and exit_code.
get_status(sandbox_id)	Return the status string ("running", "stopped", etc.).
get_metrics(sandbox_id)	Return point-in-time resource-usage metrics (memory, CPU, network, block I/O).
snapshot_sandbox(sandbox_id)	Create a snapshot. Returns {"snapshot_path": ..., "mem_file_path": ...}.
resume_sandbox(sandbox_id)	Resume a paused / snapshotted sandbox.
run_python(sandbox_id, code)	Execute arbitrary Python code inside the sandbox. Returns the stdout output.
get_platform_info(sandbox_id)	Get platform information from the sandbox. Returns a JSON string of platform data.
close()	Release the underlying connection / session.

Constructor options

HTTPClient

HTTPClient(
    host="localhost",       # Orchestrator hostname
    port=8080,              # HTTP port (default 8080)
    address=None,           # Full URL, overrides host/port (e.g. "http://proxy:9090/v1/service/sandbox")
    timeout=30.0,           # Request timeout in seconds (None = no timeout)
    session=None,           # Optional requests.Session for custom TLS / auth / retries
)

AsyncHTTPClient

AsyncHTTPClient(
    host="localhost",       # Orchestrator hostname
    port=8080,              # HTTP port (default 8080)
    address=None,           # Full URL, overrides host/port
    timeout=30.0,           # Request timeout in seconds
    session=None,           # Optional aiohttp.ClientSession
)

SandboxClient (gRPC)

SandboxClient(
    host="localhost",       # Orchestrator hostname
    port=50051,             # gRPC port (default 50051)
    address=None,           # Full address for proxy routing (e.g. "localhost:8092/v1/service/sandbox")
)

HTTPClient-only extras

The HTTP transport includes a few additional features:

• Firecracker fields on start_sandbox: kernel_image, initrd_path, snapshot_path, mem_file_path.
• Custom timeouts per-client via the timeout parameter.
• Session injection – pass your own requests.Session for connection pooling, mutual TLS, retry policies, or authentication headers.
• Typed exceptions: SandboxHTTPError (with .status_code and .detail) and the more specific SandboxNotFoundError for 404 responses.

Response types (HTTP client)

Class	Fields
ExecResult	stdout: str, stderr: str, exit_code: int
MetricsResult	memory_usage_bytes, memory_limit_bytes, memory_percent, cpu_percent, pids_current, net_rx_bytes, net_tx_bytes, block_read_bytes, block_write_bytes
SnapshotResult	snapshot_path: str, mem_file_path: str

All response dataclasses are frozen (immutable).

Context manager

All clients support the context-manager protocol (with for sync, async with for async):

from flash_sandbox import HTTPClient

with HTTPClient(host="localhost") as client:
    sid = client.start_sandbox(type="docker", image="alpine:latest")
    client.stop_sandbox(sid)
# Connection is automatically closed here.

Proxy / reverse-proxy support

Both clients support routing through a reverse proxy that uses path-based routing. Pass the full address including the path prefix:

# HTTP through a proxy
http_client = HTTPClient(address="http://proxy.example.com:8092/v1/service/sandbox")

# gRPC through a proxy
grpc_client = SandboxClient(address="proxy.example.com:8092/v1/service/sandbox")

Running tests

pip install -e ".[dev]"
pytest tests/