Environment
TheMSB_BACKEND environment variable selects a backend for a single command or shell, unless an administrator has set a managed active profile:
MSB_API_KEY does not select cloud by itself. MSB_API_URL only overrides the cloud endpoint and does not select cloud either.
SDK
Programmatic selection wins over environment and profile resolution. Use it when the application should decide regardless of where it is launched:Profiles
Profiles are named backend configurations in~/.microsandbox/config.json. Use them when you switch regularly or want a shared default for an environment:
active_profile sets the default. MSB_PROFILE=<name> selects another profile for one command:
api_key_ref. The optional url field defaults to https://api.microsandbox.dev; set it only for a development, self-hosted, or on-premises control plane. See the profiles schema for every field and credential-reference format.
Precedence
Backend resolution uses this order:- Programmatic backend set by the SDK
- Managed
active_profile, if supplied MSB_BACKEND=local|cloudMSB_PROFILE=<name>- User
active_profile - Local runtime
active_profile set to null or an empty string clears saved and environment-selected profiles while preserving MSB_BACKEND. With no explicit backend, it uses the local fallback. To enforce local execution over MSB_BACKEND, select a named managed profile with backend: local. Managed profile entries replace same-named user entries. See Managed deployment for deployment and file format. An explicitly constructed SDK backend keeps its identity. Both local and cloud backends apply managed sandbox settings and host-side SSH policy.
Selecting a cloud profile with MSB_PROFILE or active_profile is 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.
Permit local, cloud, or both
Set"allowed_backends": ["local"], ["cloud"], or ["local", "cloud"] in user config or managed overrides. The default is both. An empty list is invalid; null removes the restriction. Managed values replace user values.
Permission is separate from selection. A cloud-only policy rejects local selection; it does not select cloud for you. Checks apply when standard SDK or CLI backends are constructed, including explicitly supplied backends. Existing backend instances keep their captured settings.
Use msb context list to inspect profiles without loading credentials, msb context use <name> to save a preference, and msb context reset to remove it. See context commands for precedence and recovery.
Verify
Usemsb context to inspect the backend kind, selection source, profile, and cloud API URL without exposing the API key: