Configuration file

Sandbox configuration is a reusable, sparse definition for one sandbox. Load it with msb run, msb create, or msb install; explicit CLI arguments are applied on top. The file may have any name when passed with --conf.

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

msb run --conf sandbox.yaml -- start
msb create --conf sandbox.yaml --name agent
msb install --conf sandbox.yaml --name agent

Sandbox configuration is never auto-discovered. Every root or scoped configuration file must be supplied explicitly with its corresponding flag.

Sparse configuration

Every config file may provide only the fields it owns. Required fields are checked after root config, scoped config, and command-line inputs are merged, so a positional image can complete a network-only file:

# net-policy.yaml
network:
  policy: public
  allow:
    - "api.openai.com"
  deny:
    - "169.254.169.254"

msb run python --conf net-policy.yaml

If neither the files nor the arguments provide an image, the command fails before pulling an image or creating sandbox state.

Scoped config files

Scoped flags accept the contents of one field or field group without its root wrapper. They are useful for focused policies that should fail on unrelated fields.

Flag	Accepted fields
`--conf PATH`	Any sandbox configuration field
`--net-conf PATH`	`policy`, `allow`, `deny`, `ports`, `dns`, `tls`, `trust_host_cas`, `max_connections`
`--resource-conf PATH`	`cpus`, `memory`, `max_duration`, `idle_timeout`, `rlimits`
`--runtime-conf PATH`	`workdir`, `shell`, `user`, `hostname`, `security`, `entrypoint`, `cmd`, `env`, `labels`, `init`
`--fs-conf PATH`	`mounts`, `patch_files`, `patches`
`--secret-conf PATH`	A map of secret names to secret definitions
`--script-conf PATH`	A map of script names to shell snippets

For example, --net-conf expects this unwrapped document:

policy: public
allow:
  - "api.openai.com"
deny:
  - "169.254.169.254"

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

Passing network: {...} to --net-conf is an error; use --conf for a root-shaped document. Every root and scoped config flag is repeatable, and different config flag kinds may be interleaved freely.

Precedence and merging

Configuration resolves from lower to higher precedence:

Built-in and global config.json defaults
Every --conf and scoped config occurrence, from left to right on the command line
Explicit non-config CLI flags and positional arguments

Higher-precedence scalars replace lower values. Maps merge by key, including nested init, network.dns, network.tls, and secret definitions. A list supplied by a higher-precedence config file replaces the lower list. Network policy is atomic: when a higher config source supplies any of policy, allow, or deny, those values replace the complete lower-layer policy while sibling network fields continue to merge. Repeating the same config flag works exactly like interleaving different config flags: each file overlays everything to its left. --net-conf cannot be combined with --net, --no-net, --net-rule, or --net-default*. When network policy is loaded through a root --conf file instead, a policy CLI flag replaces it, while --net-rule remains additive and is evaluated before rules loaded from the file.

# Files overlay left to right; the explicit CLI value wins over every file.
msb run python \
  --conf base.yaml \
  --resource-conf standard.yaml \
  --conf project.yaml \
  --resource-conf large.yaml \
  --memory 12G

Relative host paths are resolved against the file that contains them. Paths inside a file listed by patch_files are resolved against that patch file.

Rust SDK patches

SandboxConfigPatch is the typed sparse representation for per-sandbox configuration. Its nested patch types are generated from the canonical sandbox configuration, compose with right-hand-side precedence, and are applied by SandboxBuilder::overlay before later fluent builder calls:

use microsandbox::{
    EnvVar, Sandbox, SandboxConfigPatch, SandboxResourcesPatch,
};

let resources_patch = SandboxResourcesPatch::new()
  .max_memory_mib(1024)
  .memory_mib(1024)
  .max_cpus(2)
  .cpus(2);

let patch = SandboxConfigPatch::new()
    .resources(resources_patch)
    .env(vec![EnvVar::new("MODE", "production")]);

let sandbox = Sandbox::builder("agent")
    .image("python:3.12")
    .overlay(patch)
    .memory(2048) // Explicit builder calls are higher precedence.
    .create()
    .await?;

Every canonical nested struct has a corresponding generated patch type. Adding a field to the source struct adds it to the patch API and its overlay/apply implementations automatically. Patch types do not read YAML, resolve relative paths, expand ${ENV}, or carry registry credentials and snapshot-selection state; those remain file-adapter or explicit builder responsibilities. SandboxConfig remains the complete durable configuration. Collection fields are atomic unless their canonical field declares a merge strategy. Environment variables merge by variable name, labels and scripts merge by map key, and secret entries merge by environment-variable name; higher values win when keys match. Their normal setters merge, while generated replace_* methods replace the complete collection. Calling clear_* removes that field from the patch, so applying the patch leaves the lower-layer value unchanged. The generated model replaces the earlier handwritten patch hierarchy. Use SandboxResourcesPatch, SandboxRuntimeOptionsPatch, NetworkSpecPatch, SandboxPolicyPatch, and SecretsConfigPatch in place of the former resource, runtime, network, network-policy, and secret patch types. Filesystem, script, image, and init changes are now expressed directly through SandboxConfigPatch and its canonical nested patches. The old LocalConfig name remains as a deprecated alias of GlobalConfig.

Schema

Image and registry

The common image form is a string. Local paths beginning with ., .., or / are resolved as bind roots or disk images; other strings are OCI references.

image: "python:3.12"
pull_policy: missing # missing | always | never
registry:
  username: "deploy"
  password_env: "REGISTRY_TOKEN"

Use the object form to select a source explicitly:

image: { oci: "python:3.12", upper_size: "8G" }
image: { snapshot: "prepared-agent" }
image: { disk: "./ubuntu.qcow2", fstype: ext4 }
image: { bind: "./rootfs" }

Exactly one source is allowed. Project layer references are not valid in single-sandbox configuration; consume a published layer as an OCI reference instead.

Resources and lifecycle

cpus: 2
memory: "1G"
max_duration: "12h"
idle_timeout: "10m"
rlimits:
  - { resource: nofile, soft: 8192, hard: 16384 }
  - { resource: nproc, soft: 512 }

When hard is omitted it equals soft.

Runtime

workdir: "/app"
shell: "/bin/bash"
user: "app"
hostname: "api"
security: restricted # default | restricted
entrypoint: ["/usr/bin/tini", "--"]
cmd: ["python", "app.py"]
env:
  MODE: "production"
labels:
  team: "platform"
init:
  cmd: auto # auto or an absolute guest path
  args: []
  env: {}

cmd is the default workload for msb run. msb create stores it without launching it.

Mounts

A string mount is a config-relative bind mount using the same SOURCE:TARGET[:OPTIONS] option grammar as a bind passed to -v/--volume. Options include ro, rw, noexec, nosuid, nodev, follow-root-symlinks, stat-virt=strict|relaxed|off, host-perms=private|mirror, quota=<size>, and paired uid=<N>,gid=<N>:

mounts:
  - "./src:/app"
  - "./certs:/etc/app/certs:ro,noexec"
  - "./workspace:/workspace:uid=1000,gid=1000"

Object mounts require exactly one source and a guest target:

mounts:
  - bind: "./src"
    target: "/app"
    stat_virtualization: strict
    host_permissions: private
    uid: 1000
    gid: 1000
  - named: cache
    target: "/var/cache/app"
    create: ensure-exists
  - tmpfs: { size: "256M" }
    target: "/run"
    noexec: true
  - disk: "./seed.qcow2"
    target: "/seed"
    format: qcow2
    fstype: ext4
    readonly: true

All mount kinds accept readonly, noexec, nosuid, and nodev. stat_virtualization, host_permissions, and paired uid/gid apply only to bind and directory-backed named mounts. Ownership changes only the guest fallback for files without a per-file stat override; it does not change host inode ownership. Duplicate guest targets are rejected.

Rootfs patches

Patch files run first in listed order, followed by inline patches:

patch_files:
  - "./patches/common.yaml"
patches:
  - copy_file:
      {
        src: "./config.toml",
        dst: "/etc/app/config.toml",
        mode: "0644",
        replace: true,
      }
  - copy_dir: { src: "./certs", dst: "/etc/app/certs" }
  - text: { path: "/etc/app/build.txt", content: "release", mode: "0644" }
  - file:
      { path: "/etc/app/blob.bin", content_base64: "SGVsbG8=", mode: "0600" }
  - mkdir: { path: "/var/cache/app", mode: "0755" }
  - symlink: { target: "/etc/app/config.toml", link: "/etc/app/active.toml" }
  - append: { path: "/etc/hosts", content: "10.0.0.5 db.internal\n" }
  - remove: { path: "/etc/motd" }

A patch file has one top-level patches list using the same operations. File modes must be quoted four-digit octal strings.

Network

Use a preset string for the common cases:

network: public # none | public | open

public, the default, permits public internet access while blocking private, loopback, link-local, and metadata destinations. none denies ingress and egress. open is unrestricted. The object form adds rules and network services:

network:
  policy: public
  allow: ["api.openai.com", "*.stripe.com"]
  deny: ["169.254.169.254"]
  ports: ["8000:8000", "9100:9100/udp"]
  dns:
    rebind_protection: true
    nameservers: ["1.1.1.1", "8.8.8.8"]
    query_timeout: "5s"
  tls:
    enabled: true
    bypass: ["*.internal.example"]
    verify_upstream: true
    block_quic: true
  trust_host_cas: false
  max_connections: 256

A non-empty allow list implies deny-by-default egress. Top-level ports is shorthand for network.ports; when both are present, the lists are combined and duplicate host ports are rejected.

Secrets

Every secret requires a non-empty destination allowlist. When value is omitted, the host environment variable with the same name is used. An exact ${NAME} value records NAME as the host-side source instead of copying its plaintext into durable config.

secrets:
  OPENAI_API_KEY:
    allow: ["api.openai.com"]
  DATABASE_URL:
    value: "${DB_DSN}"
    allow: ["db.internal"]
    inject: [headers]
    require_tls_identity: true

inject accepts headers, basic_auth, and query_params; it defaults to headers. Declaring a secret enables TLS interception and DNS-rebind protection.

Scripts

Scripts are named shell snippets installed as executables in /.msb/scripts, which is on PATH. The sandbox configuration’s shell selects their shebang and defaults to /bin/sh.

shell: "/bin/bash"
scripts:
  start: "python app.py"
  migrate: "alembic upgrade head"

Run a script like any other guest command:

msb run --conf sandbox.yaml -- migrate

Strict YAML and environment substitution

Sandbox configuration is data, not a templating language. The loader rejects unknown fields, duplicate keys, multiple YAML documents, anchors, aliases, merge keys, and custom tags. Bare YAML 1.1 booleans such as yes, no, on, and off are rejected. Quote modes, sizes, durations, ports, domains, image references, and other typed strings. Only ${NAME} environment substitution is supported. Substituted variables must exist when the config is loaded; an exact secret value: "${NAME}" is the exception because it records a host-side source that is resolved when the sandbox starts. Shell-style operators such as ${NAME:-fallback}, includes, templates, loops, and expressions are not supported. Project envelope fields such as sandboxes, volumes, and layers, plus per-project fields such as depends_on, are rejected in single-sandbox configuration.

Getting Started

SDKs

CLI

Sparse configuration

Scoped config files

Precedence and merging

Rust SDK patches

Schema

Image and registry

Resources and lifecycle

Runtime

Mounts

Rootfs patches

Network

Secrets

Scripts

Strict YAML and environment substitution

​Sparse configuration

​Scoped config files

​Precedence and merging

​Rust SDK patches

​Schema

​Image and registry

​Resources and lifecycle

​Runtime

​Mounts

​Rootfs patches

​Network

​Secrets

​Scripts

​Strict YAML and environment substitution

Sparse configuration

Scoped config files

Precedence and merging

Rust SDK patches

Schema

Image and registry

Resources and lifecycle

Runtime

Mounts

Rootfs patches

Network

Secrets

Scripts

Strict YAML and environment substitution