Backends - Microsandbox

The SDKs and the msb CLI expose one surface with two backends behind it: the local runtime on your machine, and microsandbox cloud. Every call resolves a backend the same way, and the same code runs against either. The local runtime is the default; cloud is opt-in.

For hosted cloud usage, select cloud explicitly and provide the API key separately:

bash

export MSB_BACKEND=cloud
export MSB_API_KEY="msb_..."

Leaving cloud credentials in a shell does not unexpectedly reroute local workloads. MSB_API_URL only overrides the cloud endpoint; neither it nor MSB_API_KEY selects cloud on its own.

Environment

The MSB_BACKEND environment variable forces a backend for a single command or shell:

bash

MSB_BACKEND=local msb run python -- python -V   # force local
MSB_BACKEND=cloud msb ls                        # explicit cloud

Code

Programmatic selection wins over environment and profile resolution. Use it when the application should decide regardless of its environment:

<CodeGroup> ```rust Rust use microsandbox::{set_default_backend, CloudBackend, LocalBackend};

// reads MSB_API_KEY set_default_backend(CloudBackend::from_env()?);

// or: pass the key explicitly set_default_backend(CloudBackend::with_api_key(api_key)?);

// or: force the local runtime set_default_backend(LocalBackend::lazy());


```typescript TypeScript
import { setDefaultBackend } from "microsandbox";

setDefaultBackend({ kind: "cloud", apiKey: process.env.MSB_API_KEY! });

// or: force the local runtime
setDefaultBackend("local");

python

import os
from microsandbox import set_default_backend

set_default_backend("cloud", api_key=os.environ["MSB_API_KEY"])

# or: force the local runtime
set_default_backend("local")

// Select cloud explicitly and provide its credential before the first call.
os.Setenv("MSB_BACKEND", "cloud")
os.Setenv("MSB_API_KEY", apiKey)

</CodeGroup>

Profiles

Profiles give named backend configurations in config.json, useful when you switch between local and cloud regularly or keep per-project defaults:

json

{
  "active_profile": "prod",
  "profiles": {
    "prod": {
      "backend": "cloud",
      "api_key_ref": "env:MSB_API_KEY"
    },
    "local": {
      "backend": "local"
    }
  }
}

active_profile sets the default. MSB_PROFILE=<name> overrides it for a single command:

bash

MSB_PROFILE=prod msb run python -- python -V

Cloud profiles require api_key_ref. The url field is optional and defaults to https://api.microsandbox.dev; set it only for a development, self-hosted, or on-prem control plane. See the profiles schema for the allowed fields and credential-reference formats.

Resolution order

Backend resolution uses this order:

Programmatic backend set by the SDK
MSB_BACKEND=local|cloud
MSB_PROFILE=<name>
active_profile
Local runtime

Selecting a cloud profile with MSB_PROFILE or active_profile is also explicit cloud intent when that profile has "backend": "cloud". MSB_BACKEND=cloud without a usable API key or cloud profile returns a configuration error; it never falls back to local execution.

Inspect the active backend

Use msb context before running CLI commands when you want to confirm where sandboxes will execute. JSON is available for scripts:

bash

msb context
msb context --format json

msb ctx is a shorter alias for msb context.

The SDKs expose the same secret-safe information. It includes the backend kind, cloud API URL, selection source, and profile when applicable, but never the API key:

<CodeGroup> ```typescript TypeScript import { defaultBackendInfo } from "microsandbox";

console.log(defaultBackendInfo()); console.log(sandbox.backendKind);


```python Python
from microsandbox import default_backend_info

print(default_backend_info())
print(sandbox.backend_kind)

rust

let info = microsandbox::default_backend_info();
println!("{}", info.kind.as_str());
println!("{}", sandbox.backend_kind().as_str());

info, err := microsandbox.DefaultBackendInfo()
if err != nil {
    return err
}
fmt.Println(info.Kind)
fmt.Println(sandbox.BackendKind())

</CodeGroup>