Backends

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. Most applications never choose explicitly. A non-empty MSB_API_KEY selects the cloud; no key means the local runtime:

export MSB_API_KEY="msb_..."   # cloud
unset MSB_API_KEY              # local

The sections below are the explicit overrides, in the order they win. Select at most one.

Environment

The MSB_BACKEND environment variable forces a backend for a single command or shell, for example to use the local runtime while a key is exported:

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:

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

import { setDefaultBackend } from "microsandbox";

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

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

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")

// The Go SDK selects the backend from the environment: set MSB_API_KEY
// (or MSB_PROFILE) before the first microsandbox call.
os.Setenv("MSB_API_KEY", apiKey)

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:

Programmatic backend set by the SDK
MSB_BACKEND=local, or a non-empty MSB_API_KEY
MSB_PROFILE=<name>
active_profile
Local runtime

MSB_API_URL only overrides the cloud endpoint; it never selects the cloud backend without an API key.

Getting Started

Cloud

Sandboxes

Networking

Observability

Images

Troubleshooting

Environment

Code

Profiles

Resolution order

​Environment

​Code

​Profiles

​Resolution order

Environment

Code

Profiles

Resolution order