Microsandbox CLI YAML configuration reference

Load reusable sandbox settings with --conf. See configuration precedence for global defaults.

Common image, resource, lifecycle, environment, policy, secret, script, and patch fields work everywhere. Host-integrated networking, local rootfs forms, snapshots, replace behavior, and several runtime fields are unavailable on microsandbox cloud.

Files may have any name and contain only the fields you need. Explicit CLI arguments override their values.

# sandbox.yaml
image: "python:3.12"
cpus: 2
memory: "1G"
workdir: "/app"
mounts:
  - "./src:/app"
network:
  allow: ["api.openai.com"]
  ports: ["8000:8000"]
secret_violation_action: block-and-log
secrets:
  OPENAI_API_KEY:
    allow: ["api.openai.com"]
    substitution:
      headers: true
      query: false
      body: false
    passthrough: ["telemetry.example.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

Files are never auto-discovered; pass each file explicitly.

Sparse configuration

Required fields are checked after merging files and CLI arguments. For example, supply the image separately from 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 files contain one group of settings without its wrapper key. Unrelated fields are rejected.

Flag	Accepted fields
`--conf PATH`	Any sandbox configuration field
`--net-conf PATH`	`policy`, `allow`, `deny`, `ports`, `dns`, `tls`, `strict`, `trust_host_cas`, `max_tcp_connections`, `max_udp_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.

Combining files

Root and scoped configuration flags are repeatable and may be interleaved. The CLI applies each file from left to right, then applies explicit flags and positional arguments. See Precedence and Merge precedence for the complete resolution rules. --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; --memory wins unless managed policy overrides it.
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 applications can apply the same sparse configuration model without loading YAML. See SandboxBuilder::overlay for the typed API, merge behavior, and migration from the earlier patch types.

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
  strict: true
  trust_host_cas: false
  max_tcp_connections: 256

A non-empty allow list implies deny-by-default egress. strict defaults to true and requires hostname-based allow rules to use an inspectable request authority. Plain HTTP exposes that authority in Host; HTTPS only exposes it when TLS interception is enabled and not bypassed. Without that visibility, strict mode denies HTTPS that would otherwise be allowed only by a hostname rule. Set strict: false to opt out. 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"]
    substitution:
      headers: false
      query: false
      body: true
    passthrough: ["audit.internal"]
    violation_action: block-and-terminate
    require_tls_identity: true

substitution controls headers, query parameters, and request bodies independently; it defaults to headers only, and Basic authentication follows the header setting. Disabled locations still block the placeholder unless the destination appears in passthrough. secret_violation_action sets the sandbox-wide blocking action, while a per-secret violation_action overrides it. 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

Validation

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.

UDP session limit

Set max_udp_connections in the network configuration, or pass --max-udp-connections 512. The default is unlimited in single-tenant mode and 1,024 relay sessions in multi-tenant mode; zero explicitly selects unlimited. At capacity, new sessions evict the least recently active session. max_connections and --max-connections remain deprecated TCP-only aliases for max_tcp_connections and --max-tcp-connections. Specifying both TCP names in one configuration or command is an error. The UDP limit is independent.

Getting Started

SDKs

CLI

Configuration

Sparse configuration

Scoped config files

Combining files

Schema

Image and registry

Resources and lifecycle

Runtime

Mounts

Rootfs patches

Network

Secrets

Scripts

Validation

UDP session limit

​Sparse configuration

​Scoped config files

​Combining files

​Schema

​Image and registry

​Resources and lifecycle

​Runtime

​Mounts

​Rootfs patches

​Network

​Secrets

​Scripts

​Validation

​UDP session limit

Sparse configuration

Scoped config files

Combining files

Schema

Image and registry

Resources and lifecycle

Runtime

Mounts

Rootfs patches

Network

Secrets

Scripts

Validation

UDP session limit