miosa-sandbox

miosa-sandbox is the compatibility package for applications that still import miosa_sandbox. It delegates sandbox, computer, transport, error, and response behavior to the canonical miosa Python SDK.

New applications should install and import miosa directly.

Install

pip install miosa-sandbox

Version 0.2.0 requires the canonical miosa==1.3.5 package.

Compatibility API

from miosa_sandbox import MIOSA

with MIOSA(api_key="msk_...") as client:
    with client.sandboxes.create() as sandbox:
        result = sandbox.exec("python3 -c 'print(1 + 1)'")
        print(result.stdout)

MIOSA and AsyncMIOSA preserve the legacy class names. Returned handles are the canonical miosa.resources.sandboxes.Sandbox and AsyncSandbox classes. All sandbox execution, file, lifecycle, usage, and response decoding behavior therefore comes from miosa.

When no size or exact resource tuple is supplied, this compatibility package requests the canonical small sandbox contract. The small contract is 2 vCPU, 4096 MiB memory, and 10240 MiB disk.

Canonical ownership selectors can be passed directly:

sandbox = client.sandboxes.create(
    workspace_id="workspace_123",
    project_id="project_123",
    external_user_id="customer_123",
)

Ownership fields, size, resource_contract, and usage() are exposed on sync and async sandbox handles.

Runtime selection

Every sandbox create runs on a runtime backend. Pass runtime= to sandboxes.create() to pin it explicitly:

sandbox = client.sandboxes.create(runtime="firecracker")  # full microVM (default)
sandbox = client.sandboxes.create(runtime="soma")         # fastest start for supported Linux images
sandbox = client.sandboxes.create(runtime="auto")         # let the platform pick

The selector travels on the wire as runtime_profile; runtime is never sent as a key of its own. Omit runtime= to let the platform apply its default (firecracker). An unrecognized value raises ValueError before any request is made. runtime= is also accepted by create_agent_workspace() and get_or_create(), which build a create body too.

Check the live gate state before asking for a runtime - a requested runtime that is currently unavailable is rejected by the control plane:

for runtime in client.sandboxes.runtimes.list():
    print(runtime["id"], runtime["available"], runtime["unavailable_reason"])

# {'id': 'firecracker', 'runtime_profile': 'standard', 'available': True, ...}
# {'id': 'soma', 'runtime_profile': 'soma', 'available': False,
#  'unavailable_reason': 'GLOBAL_GATE_CLOSED', ...}

client.runtimes.list() (the canonical accessor) returns the same catalog. Each entry is a SandboxRuntimeInfo with id, runtime_profile, label, description, default, available, unavailable_reason, and a capabilities block (browser, network_egress, persistence, pause, gpu, max_shape). unavailable_reason is null when available is true, otherwise a machine code such as GLOBAL_GATE_CLOSED or ORG_RESTRICTED.

The async client mirrors this exactly:

sandbox = await client.sandboxes.create(runtime="soma")
runtimes = await client.sandboxes.runtimes.list()

Migration

Replace miosa-sandbox with miosa and rename the client imports when convenient:

from miosa import AsyncMiosa, Miosa

The canonical SDK documentation is at https://miosa.ai/docs/sdks/python.

License

MIT