How to Configure microsandbox: A Complete Guide to YAML Files, CLI Flags, and SDK Usage

microsandbox uses a layered YAML-based configuration system where files are merged left-to-right with CLI flags taking final precedence, defined in SandboxConfigPatch and processed through SandboxBuilder::configure in the Rust SDK.

The microsandbox runtime from superradcompany/microsandbox is entirely driven by declarative configuration files written in YAML. These files describe everything from container images and resource limits to network policies and secrets injection. Understanding how to properly configure microsandbox unlocks its full potential for running isolated, resource-constrained workloads.

Configuration Basics and Precedence

The microsandbox CLI loads configuration through a deterministic three-layer merge system:

1. Built-in defaults from config.json
2. Configuration files left-to-right on the command line
3. Explicit non-config CLI flags and positional arguments

Higher-precedence scalar values replace lower ones, while maps merge by key (including nested fields like network.dns). Lists supplied later completely replace earlier lists. This merging logic lives in the Rust SDK's SandboxConfigPatch → SandboxBuilder::configure pipeline in crates/cli/lib/sandbox_config.rs (lines 13-30).

Minimal Configuration File

A basic sandbox.yaml includes image selection, resources, mounts, networking, secrets, and scripts:

# sandbox.yaml

image: "python:3.12"
cpus: 2
memory: "1G"
workdir: "/app"
mounts:
  - "./src:/app"
network:
  allow: ["api.openai.com"]
  ports: ["8000:8000"]
secrets:
  OPENAI_API_KEY:
    allow: ["api.openai.com"]
scripts:
  start: "python app.py"

Run this configuration with:

msb run --conf sandbox.yaml -- start

When executed, the CLI parses this file into a typed SandboxConfigPatch representation defined in crates/cli/lib/sandbox_config.rs (lines 16-25), then overlays any additional flags before constructing the final SandboxConfig consumed by the runtime.

Core Configuration Sections

Each section maps to specific Rust types in the microsandbox codebase:

Section	Purpose	Key Rust Types
Image & Registry	OCI reference, snapshot, bind, or disk image selection	SandboxImagePatch, ImageConfig
Resources & Lifecycle	CPU cores, memory limits, rlimits, idle timeout, max duration	ResourceConfigPatch
Runtime	Working directory, shell, user, entrypoint, environment variables, labels, init hook	RuntimeConfigPatch
Mounts	Bind mounts, read-only mounts, patch file applications	MountConfig, PatchConfig
Network	Host allow/deny rules, port forwarding, DNS configuration, TLS, policy, connection limits	NetworkConfigPatch, DnsConfigPatch
Secrets	Secure value injection with host-based allow-lists	SecretConfigPatch
Scripts	Named executable snippets invoked via msb script	ScriptConfigPatch
Patches	JSON/JSON5 patches applied to final configuration	PatchConfig

The low-level type definitions reside in packages/microsandbox-types/rust/lib/domain.rs. For example, DnsConfig is defined at lines 2654-2664. The network stack consumes normalized configuration through NormalizedDnsConfig built from raw DnsConfig in crates/network/lib/dns/common/config.rs (lines 10-38).

Using Scoped Configuration Files

For use cases requiring only specific configuration subsets, microsandbox supports scoped flags that accept unwrapped YAML documents:

Flag	Accepts
--conf	Full SandboxConfigPatch
--net-conf	NetworkConfigPatch fields only
--fs-conf	Filesystem/mount configuration
--runtime-conf	RuntimeConfigPatch fields only

These scoped files parse into the same patch types and merge using identical precedence rules. Reference the flag table in docs/cli/configuration.mdx (lines 61-68) for exact field listings per flag.

Combining Base and Network-Only Configurations

msb run python \
  --conf base.yaml \
  --net-conf net-policy.yaml

Programmatic Configuration with the Rust SDK

For embedded applications, configure microsandbox directly in Rust using the builder pattern:

use std::collections::BTreeMap;
use microsandbox::{
    ResourceConfigPatch, RuntimeConfigPatch, Sandbox, SandboxConfigPatch, SandboxImagePatch,
};

let patch = SandboxConfigPatch::new()
    .image(SandboxImagePatch::Image("python:3.12".into()))
    .overlay(ResourceConfigPatch::new().cpus(2).memory_mib(1024))
    .overlay(RuntimeConfigPatch::new().env(BTreeMap::from([
        ("MODE".into(), "production".into()),
    ])));

let sandbox = Sandbox::builder("my-agent")
    .configure(patch)
    .memory(2048)          // explicit builder call – higher precedence
    .create()
    .await?;

The SandboxBuilder and SandboxConfigPatch types are exported from sdk/rust/lib/sandbox/mod.rs.

Advanced: JSON Patches and Secrets Injection

Applying Configuration Patches

Create incremental modifications using JSON/JSON5 patch files:

// patch.json
{
  "network": {
    "allow": ["example.com"],
    "ports": ["8080:80"]
  }
}

msb run --conf sandbox.yaml --patch-files patch.json -- start

Secret Configuration with Host Restrictions

Define secrets with fine-grained host allow-lists to prevent token exfiltration:

secrets:
  GITHUB_TOKEN:
    allow:
      - "api.github.com"

Export the secret and run:

export GITHUB_TOKEN=ghp_...
msb run --conf sandbox.yaml -- start

Key Source Files for Configuration Reference

File	Role
docs/cli/configuration.mdx	Human-readable YAML specification, precedence rules, scoped flags
crates/cli/lib/sandbox_config.rs	CLI parser converting YAML to SandboxConfigPatch
packages/microsandbox-types/rust/lib/domain.rs	Core typed definitions (DnsConfig, NetworkConfig, SecretConfig)
crates/network/lib/config/types.rs	Network-specific configuration structs
crates/network/lib/dns/common/config.rs	DNS configuration normalization for runtime
sdk/rust/lib/sandbox/mod.rs	Public Rust SDK (SandboxBuilder, SandboxConfigPatch)
sdk/python/README.md, sdk/node-ts/README.md	Language-specific SDK examples matching YAML schema

Summary

• microsandbox configuration uses layered YAML files merged with deterministic precedence: defaults → config files → CLI flags
• All configuration flows through SandboxConfigPatch and SandboxBuilder::configure in the Rust SDK
• Eight core sections cover images, resources, runtime, mounts, network, secrets, scripts, and patches
• Scoped flags (--net-conf, --fs-conf, etc.) enable partial configuration for specific use cases
• The packages/microsandbox-types crate defines authoritative type structures referenced across all SDKs
• Secrets support host-based allow-lists for secure API token injection

Frequently Asked Questions

What file format does microsandbox configuration use?

microsandbox uses YAML for all configuration files. The CLI also accepts JSON and JSON5 for patch files specified via --patch-files. All formats parse into the same internal SandboxConfigPatch representation.

How do CLI flags override configuration file values?

CLI flags take highest precedence in the merge order. Scalar values from flags replace file values entirely. Maps merge by key, so a flag like --network.allow adds to rather than replaces the file's allow list. Lists from later sources completely replace earlier lists.

Can I split configuration across multiple files?

Yes. Pass multiple --conf flags or combine scoped flags like --conf base.yaml --net-conf network.yaml. Files process left-to-right, with each subsequent file layering over previous ones according to the precedence rules documented in docs/cli/configuration.mdx.

Where are the authoritative type definitions for configuration?

The microsandbox-types crate at packages/microsandbox-types/rust/lib/domain.rs contains ground-truth structs like DnsConfig, NetworkConfig, and SecretConfig. These Rust definitions propagate to all language SDKs including Python and Node.js/TypeScript.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}