Choosing a runtime

A sandbox runs on one of two engines: Firecracker, MIOSA’s long-standing default, or SOMA, MIOSA’s own open-source VMM. Select one with the runtime option, which travels on the wire as the runtime_profile field.

The runtimes

Runtime	`runtime_profile`	What it is
Firecracker	`standard`	Full machine. The default for every size and template.
SOMA	`soma`	Fastest start for supported sandbox images.
Auto	`auto`	Let the platform pick the best runtime for the request.

runtime is the name the SDKs and the CLI use; the REST field is runtime_profile. The mapping is firecracker to standard, soma to soma, and auto to auto. Omitting the field is treated exactly as standard. A value outside those three is refused with 422 INVALID_SANDBOX_RUNTIME_PROFILE, and the error names the allowed set.

List the runtimes your organization offers

GET /api/v1/sandboxes/runtimes reports the runtimes available to your organization and what each runtime reports it supports today.

GET /api/v1/sandboxes/runtimes
Authorization: Bearer msk_u_...

{
  "data": [
    {
      "id": "firecracker",
      "runtime_profile": "standard",
      "label": "Firecracker",
      "description": "Full machine. The default for every size and template.",
      "default": true,
      "available": true,
      "unavailable_reason": null,
      "capabilities": {
        "browser": true,
        "network_egress": true,
        "persistence": true,
        "pause": true,
        "gpu": false,
        "max_shape": { "cpu_count": 16, "memory_mb": 32768, "disk_size_mb": 163840 }
      }
    },
    {
      "id": "soma",
      "runtime_profile": "soma",
      "label": "SOMA",
      "description": "Fastest start for supported sandbox images.",
      "default": false,
      "available": false,
      "unavailable_reason": "GLOBAL_GATE_CLOSED",
      "capabilities": {
        "browser": false,
        "network_egress": false,
        "persistence": false,
        "pause": true,
        "gpu": false,
        "max_shape": { "cpu_count": 8, "memory_mb": 16384, "disk_size_mb": 40960 }
      }
    },
    {
      "id": "auto",
      "runtime_profile": "auto",
      "label": "Auto",
      "description": "Let the platform pick the best runtime for the request.",
      "default": false,
      "available": true,
      "unavailable_reason": null,
      "capabilities": {
        "browser": true,
        "network_egress": true,
        "persistence": true,
        "pause": true,
        "gpu": false,
        "max_shape": { "cpu_count": 16, "memory_mb": 32768, "disk_size_mb": 163840 }
      }
    }
  ]
}

Read available before you offer a runtime. When it is false, unavailable_reason says why:

GLOBAL_GATE_CLOSED - the platform has not enabled SOMA for customer traffic yet.
ORG_RESTRICTED - SOMA is turned off for your organization by policy.
NOT_CONFIGURED - SOMA is switched on but has no default capacity configured yet.

The capabilities flags state what a runtime does today. They come from this endpoint, so read the entry for the runtime you plan to use instead of inferring a capability from its name.

Choose a runtime on create

miosa runtimes list prints each runtime with its availability and reason, so you can see whether SOMA is offered to your organization before selecting it.

If a runtime cannot serve the requested shape, create is refused with 422 SOMA_RUNTIME_UNSUPPORTED_REQUEST, naming the runtime’s maximum shape, before any machine is admitted. A sandbox response carries runtime: "firecracker" or "soma", the engine it actually runs on, so an auto request that fell back reports "firecracker".

What happens when you ask for SOMA

soma and auto are checked against a trusted runtime policy for your organization before any host work starts. If the request cannot be honoured, create fails closed with a typed error rather than silently running on the other engine. There is never a silent fallback.

Once your organization is enabled, a SOMA create needs two things to succeed:

An enabled runtime policy for your organization that carries the SOMA requirements.
Qualified capacity. A host profile that is approved, has a fresh host-truth observation, and holds a certified Generation for the requested shape.

Request access

SOMA is in early access, and access is granted per organization.

Email support@miosa.ai with the subject SOMA early access: <org>, naming the organization you want enabled.
We enable the SOMA runtime policy for that organization.
Create sandboxes with runtime_profile: "soma", or "auto" to let the policy choose.

Feature parity and gaps

What is the same on both engines:

The sandbox API contract, response shapes, and error codes.
Named resource contracts, from xs up to xl.
exec, streaming output, the filesystem API, and lifecycle operations, including pause and resume.
Pricing and billing, which accrue per vCPU-second and GiB-second regardless of engine.

What to confirm before you switch:

Only sandboxes take a runtime. There is no runtime choice for desktop Computers, which run on Firecracker.
Check the capability flags. Read the runtime’s capabilities from GET /api/v1/sandboxes/runtimes and confirm the features your workload needs are enabled before you switch.
The shape ceiling is real. A request above a runtime’s max_shape is refused with 422 SOMA_RUNTIME_UNSUPPORTED_REQUEST, so stay within the advertised shape.
SOMA capacity is limited. A SOMA create needs a certified Generation for the exact shape you asked for, on a host that is approved and freshly observed.
SOMA is alpha software. Its own repository labels the engine 1.0.0-alpha.1 and keeps a claim ledger of what is proven and what is still only designed.