Skip to main content
A sandbox’s settings can come from built-in defaults, the global config.json on the machine, sandbox YAML files, and values passed directly through the CLI or an SDK. Administrator-managed settings apply above these sources. Which sources apply depends on how the sandbox is created, so the resolution order below is split between command-line and SDK usage.

​
Precedence

Layers are applied from lowest to highest precedence. When two layers set the same value, the later layer wins.
1

Built-in defaults

Used when no other layer sets a value. This layer is always present.
2

Global sandbox defaults

Loaded automatically from sandbox_defaults in ~/.microsandbox/config.json; nothing needs to be passed to load them. A missing file behaves like an empty JSON object.These defaults apply to local and cloud creation, subject to backend support. Cloud workers supply image metadata and service-side defaults.Global sandbox defaults reference
3

Sandbox configuration files

Root files are passed with --conf. Scoped files are passed with --net-conf, --resource-conf, --runtime-conf, --fs-conf, --secret-conf, or --script-conf.These files are used by the CLI only and are never auto-discovered. Every file must be named explicitly. Multiple files are applied from left to right on the command line.Sandbox config reference
4

CLI input

Explicit flags and positional arguments override user files. Use them to specialize a file for one invocation.Sandbox commands and flags
5

Managed overrides

Administrator settings apply last and override user files and explicit CLI or SDK input. See Managed deployment.

​
Merge precedence

In the command-line path, each root or scoped file overlays the files to its left. Explicit CLI input is applied after every file. Maps merge recursively for nested init, network.dns, network.tls, and secret definitions. See Combining files for CLI-specific constraints and path resolution.

​
Exceptions

Some settings resolve outside the sandbox precedence rules above.
Host-owned policy is not an overridable sandbox default. A global deployment_profile sets the local host’s isolation floor and cannot be weakened by a sandbox file, CLI flag, or SDK option.
Local or cloud selection resolves across explicit SDK selection, environment variables, profiles, and the local default. See the selection precedence. Registry authentication resolves across explicit secret names, environment variables, and the operating-system keyring. See the authentication resolution order. Registry and backend credentials should use environment or keyring references rather than workload files.

​
Existing sandboxes

Resolved values are persisted when a local sandbox is created. Editing global or sandbox configuration changes future creations, not an existing sandbox. Use msb inspect <name> --format json to inspect effective configuration and msb modify to plan or apply supported changes. See Live Modify for the complete change model.

​
Ownership

​
References

Global configuration

Look up shared defaults, host policy, registries, metrics, and backend profiles.

Sandbox config reference

Look up root and scoped YAML fields, validation, and merge behavior.

CLI sandbox commands

Look up flags for creating, running, inspecting, and modifying sandboxes.

SDK overview

Choose an SDK and configure sandboxes from application code.
For resource, placement, storage, and writeback guidance, continue to Performance.