Backends

How the SDK and CLI choose between the local runtime and the cloud

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:

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:

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:

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());

Profiles

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

{
  "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:

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:

1. Programmatic backend set by the SDK
2. MSB_BACKEND=local|cloud
3. MSB_PROFILE=<name>
4. active_profile
5. 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:

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:

TypeScript

import { defaultBackendInfo } from "microsandbox";

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