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

> Master microsandbox configuration with our complete guide. Learn YAML, CLI flags, and SDK usage to effectively set up your sandbox environment.

- Repository: [Super Rad Company/microsandbox](https://github.com/superradcompany/microsandbox)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/lib/sandbox_config.rs) (lines 13-30).

### Minimal Configuration File

A basic [`sandbox.yaml`](https://github.com/superradcompany/microsandbox/blob/main/sandbox.yaml) includes image selection, resources, mounts, networking, secrets, and scripts:

```yaml

# 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:

```bash
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`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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

```bash
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:

```rust
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`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/mod.rs).

## Advanced: JSON Patches and Secrets Injection

### Applying Configuration Patches

Create incremental modifications using JSON/JSON5 patch files:

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

```

```bash
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:

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

```

Export the secret and run:

```bash
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`](https://github.com/superradcompany/microsandbox/blob/main/crates/cli/lib/sandbox_config.rs) | CLI parser converting YAML to `SandboxConfigPatch` |
| [`packages/microsandbox-types/rust/lib/domain.rs`](https://github.com/superradcompany/microsandbox/blob/main/packages/microsandbox-types/rust/lib/domain.rs) | Core typed definitions (`DnsConfig`, `NetworkConfig`, `SecretConfig`) |
| [`crates/network/lib/config/types.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/network/lib/config/types.rs) | Network-specific configuration structs |
| [`crates/network/lib/dns/common/config.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/network/lib/dns/common/config.rs) | DNS configuration normalization for runtime |
| [`sdk/rust/lib/sandbox/mod.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/mod.rs) | Public Rust SDK (`SandboxBuilder`, `SandboxConfigPatch`) |
| [`sdk/python/README.md`](https://github.com/superradcompany/microsandbox/blob/main/sdk/python/README.md), [`sdk/node-ts/README.md`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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.