Tuning

Change sandbox settings without recreating it

Local-only

A sandbox’s configuration is the host-side record that says how to run it: image, CPU and memory, environment, labels, mounts, network policy, secrets, and lifecycle settings.

Some configuration is fixed when the VM boots. Some can change while the sandbox is running. Use modify when you want to change an existing sandbox without recreating it.

Create time

Most settings are chosen when you create the sandbox. If the sandbox may need more CPU or memory later, set max_cpus and max_memory above the starting size so it has live resize headroom:

Rust

let sb = Sandbox::builder("worker")
    .image("python")
    .cpus(2)
    .memory(1024)
    .max_cpus(8)
    .max_memory(4096)
    .create()
    .await?;

cpus and memory are the sandbox’s live size. max_cpus and max_memory are the ceilings it can grow to while running. They default to the starting size, so a sandbox created without them has no growth headroom.

Reserving headroom is cheap: spare vCPUs stay parked, and spare memory is only backed once the guest uses it.

Change model

Use modify to plan or apply a patch to an existing sandbox. Every requested change is classified, and apply is all-or-nothing: if one change cannot be applied under the chosen policy, nothing changes.

Rust

let plan = sb.modify()
    .cpus(4)
    .label("tier", "web")
    .apply()
    .await?;

The plan labels each change as live, next start, requires restart, or unsupported.

Change	Effect	Notes
cpus, memory	Live within the max_* ceilings	The guest may take a moment to converge
max_cpus, max_memory	Restart or next start	These are boot-time ceilings
labels	Live	Host-side metadata; no guest process changes
env, workdir	Future execs	Running processes keep what they already have
secrets	Live for rotation	Placeholder changes need a restart
Root disk size	Restart or next start	Managed and flat OCI disks grow only; tmpfs changes on next boot
Other storage	Create or mount time	Named volumes, mount tmpfs, and user disk images are sized outside modify

Dry runs

Use a dry run to see what would happen before applying the patch:

Rust

let plan = sb.modify()
    .max_memory_mib(16 * 1024)
    .dry_run()
    .await?;

Policies

By default, modify only applies changes that do not require a restart. Use --next-start to save restart-backed changes for the next boot, or --restart to restart the sandbox and make them active now.

Rust

sb.modify()
    .max_memory_mib(16 * 1024)
    .next_start()
    .apply()
    .await?;

sb.modify()
    .env("MODE", "prod")
    .restart()
    .apply()
    .await?;

CPU and memory

Raise or lower CPUs and memory on the fly, up to the ceilings reserved at create time:

Rust

sb.modify().cpus(4).memory(2048).apply().await?;

Growing beyond max_cpus or max_memory takes a restart. A live resize does not always take hold at once, since the guest applies it in the background. The result reports per-resource progress so you can tell when it has settled.

Use msb ps to see a sandbox’s allocation as effective / max, and msb metrics to see live usage before deciding how to resize.

Labels

Labels can be added, changed, or removed through the same configuration path:

Rust

sb.modify()
    .label("tier", "web")
    .remove_label("stale")
    .apply()
    .await?;

They apply immediately because they are host-side metadata. They do not change running guest processes. For label names, bulk selection, metric attribution, and cardinality guidance, see Labels.

Env and workdir

Environment and workdir changes affect future commands only. Existing guest processes keep the environment and working directory they already have.

Rust

sb.modify()
    .env("MODE", "prod")
    .workdir("/app")
    .apply()
    .await?;

Secrets

Secrets can be added, rotated, or removed without recreating the sandbox. Guest code keeps using the same placeholder; only the value injected at the network boundary changes.

Rust

use microsandbox::sandbox::SecretSource;

sb.modify()
    .secret(|s| s
        .env("GITHUB_TOKEN")
        .source(SecretSource::Env { var: "GITHUB_TOKEN".into() })
        .allow_host("api.github.com"))
    .remove_secret("OLD_TOKEN")
    .apply()
    .await?;

For the credential model and host allow lists, see Secrets.

Storage

Resize an OCI sandbox’s root disk through modify:

Rust

sb.modify()
    .root_disk_size_mib(8192)
    .restart()
    .apply()
    .await?;

Root disk changes are offline, not live. For a running sandbox, use the restart policy to make the new size active immediately, or the next-start policy to save it without touching the running VM. A stopped sandbox grows before the new size is persisted.

The backing determines which changes are valid:

• Managed and flat OCI root disks are grow-only. Shrinking is rejected because it risks filesystem data loss.
• A tmpfs OCI root disk can grow or shrink on the next boot, but its size cannot exceed sandbox memory.
• User-supplied root disk images are not resized or deleted by microsandbox; resize the image file yourself while it is detached.
• Existing disk-backed named volumes do not have a resize operation. Their capacity is fixed when the volume is created.

The ext4 grower uses the image’s reserved metadata headroom. If an older image cannot grow to the requested size in place, recreate the sandbox with a larger root disk.

Other storage capacity is still chosen where the storage is defined:

• named volume size or quota on the volume
• tmpfs size on the mount
• disk image size in the disk image itself

For details, see Volumes, OCI images, and Disk images.

Reference

For exact flags and return fields, see msb modify and the SDK sandbox references.