Live Modify

A running sandbox does not need to be replaced just because its workload changes. modify can resize the VM, update host-side metadata, rotate existing secrets, and change the defaults used by future commands while the sandbox stays up.

A terminal changes CPU, memory, and a label while the sandbox remains running

What can modify change?

The live paths come first, but modify also plans changes that need a restart or the next start:

Change	When it takes effect	Notes
CPU and memory	Live, within the boot-time `max_*` ceilings	The VM and workload keep running
Labels	Live	Host-side metadata; guest processes do not change
Existing secret material or removal	Live	Adding a secret or changing its placeholder needs a restart
Environment and workdir	Future execs	Processes that are already running keep their current values
`max_cpus` and `max_memory`	Restart or next start	These ceilings are fixed when the VM boots
Root disk size	Restart or next start	Managed and flat OCI disks grow only; tmpfs changes on boot
Named volumes, mount tmpfs, and user disk images	Outside `modify`	Capacity is managed where the storage is defined

The default policy applies only changes that can complete without restarting. If a patch contains one restart-required change, the whole patch is rejected and the old configuration stays intact.

Modify a running sandbox

This patch doubles the running sandbox’s CPU and memory and updates a label in the same operation:

msb modify worker --cpus 4 --memory 2G --label tier=web

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

const plan = await sandbox.modify({
  cpus: 4,
  memory: 2048,
  labels: { tier: "web" },
});

plan = await sb.modify(
    cpus=4,
    memory=2048,
    labels={"tier": "web"},
)

plan, err := sb.Modify(ctx, m.ModifyOptions{
    CPUs:      4,
    MemoryMiB: 2048,
    Labels:    map[string]string{"tier": "web"},
})

The result is a modification plan showing what changed and whether each change was applied. CPU and memory can take a moment to converge inside the guest, but the new host limits are enforced immediately and the workload continues running.

Reserve resize headroom

Live growth needs capacity reserved when the VM boots. Set max_cpus and max_memory above the starting allocation when you create a sandbox that may need to scale:

msb create python --name worker \
  --cpus 2 --memory 1G \
  --max-cpus 8 --max-memory 4G

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

await using sandbox = await Sandbox.builder("worker")
  .image("python")
  .cpus(2)
  .memory(1024)
  .maxCpus(8)
  .maxMemory(4096)
  .create();

sb = await Sandbox.create(
    "worker",
    image="python",
    cpus=2,
    memory=1024,
    max_cpus=8,
    max_memory=4096,
)

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("python"),
    m.WithCPUs(2),
    m.WithMemory(1024),
    m.WithMaxCPUs(8),
    m.WithMaxMemory(4096),
)

The sandbox starts with two vCPUs and 1 GiB of memory, but it can grow live to eight vCPUs and 4 GiB. The ceilings default to the starting size, so omitting them leaves no live growth headroom. Reserving headroom is cheap: spare vCPUs stay parked, and spare memory is backed only when the guest uses it. You can lower CPU or memory live without pre-planning, then grow back up to the booted ceiling later.

Preview before applying

Use a dry run when a patch mixes settings or you are unsure whether a restart is needed:

msb modify worker --max-memory 16G --dry-run

let plan = sb.modify()
    .max_memory(16_384)
    .dry_run()
    .await?;

const plan = await sandbox.modify({
  maxMemory: 16_384,
  dryRun: true,
});

plan = await sb.modify(max_memory=16_384, dry_run=True)

plan, err := sb.Modify(ctx, m.ModifyOptions{
    MaxMemoryMiB: 16_384,
    DryRun:        true,
})

The planner classifies every requested field before it changes anything:

Disposition	Meaning
`live`	Applies without restarting the VM
`next start`	Is saved and applies the next time the sandbox starts
`requires restart`	Cannot affect the running VM under the default policy
`unsupported`	Is invalid for this sandbox or backing type

Live paths in detail

CPU and memory

Raise or lower CPU and memory while the workload runs:

msb modify worker --cpus 4 --memory 2G

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

const plan = await sandbox.modify({ cpus: 4, memory: 2048 });

plan = await sb.modify(cpus=4, memory=2048)

plan, err := sb.Modify(ctx, m.ModifyOptions{
    CPUs:      4,
    MemoryMiB: 2048,
})

Use msb ps to see allocation as effective / max, and msb metrics to check real usage before resizing. The apply result reports applied, converging, guest-refused, or failed for each resource so automation can wait for the guest to settle.

Labels

Labels are host-side metadata, so adding, changing, or removing one is immediate:

msb modify worker --label tier=web --label-rm stale

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

const plan = await sandbox.modify({
  labels: { tier: "web" },
  labelsRemove: ["stale"],
});

plan = await sb.modify(
    labels={"tier": "web"},
    labels_rm=["stale"],
)

plan, err := sb.Modify(ctx, m.ModifyOptions{
    Labels:       map[string]string{"tier": "web"},
    LabelsRemove: []string{"stale"},
})

Running guest processes do not change. The new labels are available to listing, selection, metrics attribution, and other host-side workflows. See Labels for naming and cardinality guidance.

Environment and workdir

Environment and workdir updates require no restart, but they affect only commands started after the patch:

msb modify worker --env MODE=prod --workdir /app
msb exec worker -- printenv MODE

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

let output = sb.exec("printenv", ["MODE"]).await?;

await sandbox.modify({
  env: { MODE: "prod" },
  workdir: "/app",
});

const output = await sandbox.exec("printenv", ["MODE"]);

await sb.modify(env={"MODE": "prod"}, workdir="/app")
output = await sb.exec("printenv", ["MODE"])

_, err := sb.Modify(ctx, m.ModifyOptions{
    Env:     map[string]string{"MODE": "prod"},
    Workdir: "/app",
})
out, err := sb.Exec(ctx, "printenv", []string{"MODE"})

Processes that were already running keep their original environment and working directory.

Secrets

Rotating the value of an existing secret is live because substitution happens at the host network boundary. Guest code keeps using the same placeholder while microsandbox begins injecting the new value:

msb modify worker --secret GITHUB_TOKEN@api.github.com

use microsandbox::sandbox::SecretSource;

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

const plan = await sandbox.modify({
  secrets: {
    GITHUB_TOKEN: {
      env: "GITHUB_TOKEN",
      allowedHosts: ["api.github.com"],
    },
  },
});

plan = await sb.modify(
    secrets={
        "GITHUB_TOKEN": {
            "env": "GITHUB_TOKEN",
            "allowed_hosts": ["api.github.com"],
        },
    },
)

plan, err := sb.Modify(ctx, m.ModifyOptions{
    Secrets: map[string]m.SecretModifySpec{
        "GITHUB_TOKEN": {
            Env:          "GITHUB_TOKEN",
            AllowedHosts: []string{"api.github.com"},
        },
    },
})

Adding a new secret or changing its guest-visible placeholder requires a restart because existing processes cannot receive a new placeholder. Removing a secret does not require recreating the sandbox. See Secrets for sources, host allow lists, and storage behavior.

Changes that need a boot boundary

Some settings define VM capacity or disk layout and cannot change in place:

Change	Apply now	Defer safely
Raise `max_cpus` or `max_memory`	`--restart`	`--next-start`
Grow a managed or flat OCI root disk	`--restart`	`--next-start`
Resize a tmpfs root disk	On restart	`--next-start`
Add a new secret or change its placeholder	`--restart`	`--next-start`

msb modify worker --max-memory 16G --next-start
msb modify worker --root-disk 8G --restart

sb.modify()
    .max_memory(16_384)
    .next_start()
    .apply()
    .await?;

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

await sandbox.modify({
  maxMemory: 16_384,
  policy: "next_start",
});

await sandbox.modify({
  rootDiskSize: 8192,
  policy: "restart",
});

from microsandbox import ModificationPolicy

await sb.modify(
    max_memory=16_384,
    policy=ModificationPolicy.NEXT_START,
)

await sb.modify(
    root_disk_size=8192,
    policy=ModificationPolicy.RESTART,
)

_, err := sb.Modify(ctx, m.ModifyOptions{
    MaxMemoryMiB: 16_384,
    Policy:       m.ModificationPolicyNextStart,
})

_, err = sb.Modify(ctx, m.ModifyOptions{
    RootDiskSizeMiB: 8192,
    Policy:          m.ModificationPolicyRestart,
})

--next-start saves the desired configuration without touching the running VM. --restart stops and starts the sandbox only when the patch needs it. The default policy does neither and rejects restart-required changes. Root disk resizing remains conservative: managed and flat OCI disks grow only, tmpfs can grow or shrink at the next boot, and user-supplied disk images are never resized by microsandbox. Named volume and mount capacity is managed where that storage is defined. See Volumes and Images for the storage model.

Reference

For every CLI flag and result state, see msb modify. The SDK sandbox references expose the same planner and policies for Rust, TypeScript, Python, and Go.

Getting Started

Sandboxes

Networking

Operations

Troubleshooting

What can modify change?

Modify a running sandbox

Reserve resize headroom

Preview before applying

Live paths in detail

CPU and memory

Labels

Environment and workdir

Secrets

Changes that need a boot boundary

Reference

​What can modify change?

​Modify a running sandbox

​Reserve resize headroom

​Preview before applying

​Live paths in detail

​CPU and memory

​Labels

​Environment and workdir

​Secrets

​Changes that need a boot boundary

​Reference

What can modify change?

Modify a running sandbox

Reserve resize headroom

Preview before applying

Live paths in detail

CPU and memory

Labels

Environment and workdir

Secrets

Changes that need a boot boundary

Reference