> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/cloud/overview). 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:

```bash theme={null}
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:

```bash theme={null}
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 theme={null}
  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 theme={null}
  import { setDefaultBackend } from "microsandbox";

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

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

  ```python Python theme={null}
  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")
  ```

  ```go Go theme={null}
  // 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)
  ```
</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 theme={null}
{
  "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 theme={null}
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](/configuration#profiles) 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`, or a non-empty `MSB_API_KEY`
3. `MSB_PROFILE=<name>`
4. `active_profile`
5. Local runtime

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