Python SDK Reference

from opensandbox import Sandbox
from opensandbox.models.sandboxes import SandboxImageSpec, SandboxImageAuth
from datetime import timedelta

sandbox = await Sandbox.create(
    "python:3.11",
    timeout=timedelta(minutes=30),
    env={"PYTHONPATH": "/workspace"},
    resource={"cpu": "2", "memory": "4Gi"},
)

sandbox = await Sandbox.connect(
    sandbox_id="existing-sandbox-id",
    connection_config=config
)

sandbox = await Sandbox.resume(
    sandbox_id="paused-sandbox-id",
    connection_config=config
)

info = await sandbox.get_info()
print(f"State: {info.status.state}")

endpoint = await sandbox.get_endpoint(80)
print(f"Endpoint: {endpoint.endpoint}")

metrics = await sandbox.get_metrics()
print(f"Memory: {metrics.memory_used_in_mib}MB")

await sandbox.renew(timedelta(minutes=30))

await sandbox.pause()

await sandbox.kill()

await sandbox.close()

healthy = await sandbox.is_healthy()

await sandbox.files.write_file("hello.txt", "Hello World")
content = await sandbox.files.read_file("hello.txt")

result = await sandbox.commands.run("python script.py")
print(result.logs.stdout[0].text)

metrics = await sandbox.metrics.get_metrics(sandbox.id)

from opensandbox import SandboxManager

manager = await SandboxManager.create(connection_config=config)

from opensandbox.models.sandboxes import SandboxFilter

sandboxes = await manager.list_sandbox_infos(
    SandboxFilter(states=["RUNNING"], page_size=10)
)

info = await manager.get_sandbox_info("sandbox-id")

await manager.kill_sandbox("sandbox-id")

await manager.renew_sandbox("sandbox-id", timedelta(minutes=30))

await manager.pause_sandbox("sandbox-id")

await manager.resume_sandbox("sandbox-id")

await manager.close()

from opensandbox.models.execd import RunCommandOpts, ExecutionHandlers

# Simple execution
result = await sandbox.commands.run("echo 'Hello World'")
print(result.logs.stdout[0].text)

# With handlers
handlers = ExecutionHandlers(
    on_stdout=lambda msg: print(f"STDOUT: {msg.text}"),
    on_stderr=lambda msg: print(f"STDERR: {msg.text}"),
)
result = await sandbox.commands.run(
    "python script.py",
    opts=RunCommandOpts(background=False),
    handlers=handlers
)

await sandbox.commands.interrupt("execution-id")

status = await sandbox.commands.get_command_status("execution-id")

logs = await sandbox.commands.get_background_command_logs("execution-id", cursor=0)

content = await sandbox.files.read_file("/tmp/hello.txt")
print(content)

content = await sandbox.files.read_bytes("/tmp/image.png")

async for chunk in sandbox.files.read_bytes_stream("/tmp/large-file.bin"):
    process(chunk)

from opensandbox.models.filesystem import WriteEntry

await sandbox.files.write_files([
    WriteEntry(path="/tmp/hello.txt", data="Hello World", mode=644)
])

await sandbox.files.write_file("/tmp/hello.txt", "Hello World")

from opensandbox.models.filesystem import WriteEntry

await sandbox.files.create_directories([
    WriteEntry(path="/tmp/mydir", mode=755)
])

await sandbox.files.delete_files(["/tmp/hello.txt"])

await sandbox.files.delete_directories(["/tmp/mydir"])

from opensandbox.models.filesystem import MoveEntry

await sandbox.files.move_files([
    MoveEntry(source="/tmp/old.txt", destination="/tmp/new.txt")
])

from opensandbox.models.filesystem import SetPermissionEntry

await sandbox.files.set_permissions([
    SetPermissionEntry(path="/tmp/script.sh", mode=755)
])

from opensandbox.models.filesystem import ContentReplaceEntry

await sandbox.files.replace_contents([
    ContentReplaceEntry(
        path="/tmp/config.txt",
        search="old_value",
        replace="new_value"
    )
])

from opensandbox.models.filesystem import SearchEntry

files = await sandbox.files.search(
    SearchEntry(path="/tmp", pattern="*.txt")
)
for f in files:
    print(f.path)

info_map = await sandbox.files.get_file_info(["/tmp/hello.txt"])
for path, info in info_map.items():
    print(f"{path}: {info.size} bytes")

from opensandbox.config import ConnectionConfig
from datetime import timedelta

config = ConnectionConfig(
    api_key="your-api-key",
    domain="api.opensandbox.io",
    request_timeout=timedelta(seconds=60)
)

from opensandbox import SandboxSync, SandboxManagerSync
from opensandbox.config import ConnectionConfigSync

config = ConnectionConfigSync(
    domain="api.opensandbox.io",
    api_key="your-api-key"
)

sandbox = SandboxSync.create("ubuntu", connection_config=config)
with sandbox:
    execution = sandbox.commands.run("echo 'Hello Sandbox!'")
    print(execution.logs.stdout[0].text)
    sandbox.kill()

from opensandbox.exceptions import (
    SandboxException,
    SandboxReadyTimeoutException,
    InvalidArgumentException,
)

try:
    sandbox = await Sandbox.create("python:3.11")
except SandboxReadyTimeoutException:
    print("Sandbox did not become ready in time")
except SandboxException as e:
    print(f"Sandbox error: [{e.error.code}] {e.error.message}")

import asyncio
from opensandbox import Sandbox
from opensandbox.config import ConnectionConfig
from opensandbox.models.execd import ExecutionHandlers
from datetime import timedelta

async def main():
    config = ConnectionConfig(
        domain="api.opensandbox.io",
        api_key="your-api-key"
    )

    async with await Sandbox.create(
        "python:3.11",
        timeout=timedelta(minutes=30),
        connection_config=config
    ) as sandbox:
        # Write a file
        await sandbox.files.write_file("script.py", "print('Hello World')")

        # Execute command with streaming
        handlers = ExecutionHandlers(
            on_stdout=lambda msg: print(f"Output: {msg.text}")
        )
        result = await sandbox.commands.run(
            "python script.py",
            handlers=handlers
        )

        # Get metrics
        metrics = await sandbox.get_metrics()
        print(f"Memory: {metrics.memory_used_in_mib}MB")

        # Cleanup
        await sandbox.kill()

if __name__ == "__main__":
    asyncio.run(main())