ContextQMD
Back to Microsandbox

Tuning

docs/sandboxes/tuning.mdx

0.6.910.0 KB
Original Source

<Tooltip tip="modify and live resize are not yet available on microsandbox cloud; create a replacement sandbox with the new configuration."><span className="msb-badge-limited">Limited on cloud <Icon icon="circle-info" size={11} /></span></Tooltip>

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:

<CodeGroup> ```rust Rust let sb = Sandbox::builder("worker") .image("python") .cpus(2) .memory(1024) .max_cpus(8) .max_memory(4096) .create() .await?; ```
typescript
const sb = await Sandbox.builder("worker")
    .image("python")
    .cpus(2)
    .memory(1024)
    .maxCpus(8)
    .maxMemory(4096)
    .create();
python
sb = await Sandbox.create(
    "worker",
    image="python",
    cpus=2,
    memory=1024,
    max_cpus=8,
    max_memory=4096,
)
go
sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("python"),
    m.WithCPUs(2),
    m.WithMemory(1024),
    m.WithMaxCPUs(8),
    m.WithMaxMemory(4096),
)
bash
msb create python --name worker \
  --cpus 2 --memory 1G \
  --max-cpus 8 --max-memory 4G
</CodeGroup>

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.

<CodeGroup> ```rust Rust let plan = sb.modify() .cpus(4) .label("tier", "web") .apply() .await?; ```
typescript
const plan = await sandbox.modify({
    cpus: 4,
    labels: { tier: "web" },
});
python
plan = await sb.modify(
    cpus=4,
    labels={"tier": "web"},
)
go
plan, err := sb.Modify(ctx, m.ModifyOptions{
    CPUs:   4,
    Labels: map[string]string{"tier": "web"},
})
bash
msb modify worker --cpus 4 --label tier=web
</CodeGroup>

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

ChangeEffectNotes
cpus, memoryLive within the max_* ceilingsThe guest may take a moment to converge
max_cpus, max_memoryRestart or next startThese are boot-time ceilings
labelsLiveHost-side metadata; no guest process changes
env, workdirFuture execsRunning processes keep what they already have
secretsLive for rotationPlaceholder changes need a restart
Root disk sizeRestart or next startManaged and flat OCI disks grow only; tmpfs changes on next boot
Other storageCreate or mount timeNamed 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:

<CodeGroup> ```rust Rust let plan = sb.modify() .max_memory_mib(16 * 1024) .dry_run() .await?; ```
typescript
const plan = await sandbox.modify({ maxMemory: 16384, dryRun: true });
python
plan = await sb.modify(max_memory=16384, dry_run=True)
go
plan, err := sb.Modify(ctx, m.ModifyOptions{
    MaxMemoryMiB: 16 * 1024,
    DryRun:       true,
})
bash
msb modify worker --max-memory 16G --dry-run
</CodeGroup>

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.

<CodeGroup> ```rust Rust sb.modify() .max_memory_mib(16 * 1024) .next_start() .apply() .await?;

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


```typescript TypeScript
await sandbox.modify({ maxMemory: 16384, policy: "next_start" });
await sandbox.modify({ env: { MODE: "prod" }, policy: "restart" });
python
await sb.modify(max_memory=16384, policy="next_start")
await sb.modify(env={"MODE": "prod"}, policy="restart")
go
_, err := sb.Modify(ctx, m.ModifyOptions{
    MaxMemoryMiB: 16384,
    Policy:       m.ModificationPolicyNextStart,
})
if err != nil {
    return err
}

_, err = sb.Modify(ctx, m.ModifyOptions{
    Env:    map[string]string{"MODE": "prod"},
    Policy: m.ModificationPolicyRestart,
})
bash
msb modify worker --max-memory 16G --next-start
msb modify worker --env MODE=prod --restart
</CodeGroup>

CPU and memory

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

<CodeGroup> ```rust Rust sb.modify().cpus(4).memory(2048).apply().await?; ```
typescript
await sandbox.modify({ cpus: 4, memory: 2048 });
python
await sb.modify(cpus=4, memory=2048)
go
sb.Modify(ctx, m.ModifyOptions{CPUs: 4, MemoryMiB: 2048})
bash
msb modify worker --cpus 4 --memory 2G
</CodeGroup>

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:

<CodeGroup> ```rust Rust sb.modify() .label("tier", "web") .remove_label("stale") .apply() .await?; ```
typescript
await sandbox.modify({
    labels: { tier: "web" },
    labelsRemove: ["stale"],
});
python
await sb.modify(
    labels={"tier": "web"},
    labels_rm=["stale"],
)
go
_, err := sb.Modify(ctx, m.ModifyOptions{
    Labels:       map[string]string{"tier": "web"},
    LabelsRemove: []string{"stale"},
})
bash
msb modify worker --label tier=web --label-rm stale
</CodeGroup>

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.

<CodeGroup> ```rust Rust sb.modify() .env("MODE", "prod") .workdir("/app") .apply() .await?; ```
typescript
await sandbox.modify({
    env: { MODE: "prod" },
    workdir: "/app",
});
python
await sb.modify(env={"MODE": "prod"}, workdir="/app")
go
_, err := sb.Modify(ctx, m.ModifyOptions{
    Env:     map[string]string{"MODE": "prod"},
    Workdir: "/app",
})
bash
msb modify worker --env MODE=prod --workdir /app
</CodeGroup>

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.

<CodeGroup> ```rust 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?;


```bash CLI
msb modify worker --secret [email protected]
msb modify worker --secret-rm OLD_TOKEN
</CodeGroup>

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

Storage

The local backend can resize an OCI sandbox's root disk through modify:

<CodeGroup> ```rust Rust sb.modify() .root_disk_size_mib(8192) .restart() .apply() .await?; ```
typescript
await sandbox.modify({ rootDiskSize: 8192, policy: "restart" });
python
await sb.modify(
    root_disk_size=8192,
    policy=ModificationPolicy.RESTART,
)
go
_, err := sb.Modify(ctx, m.ModifyOptions{
    RootDiskSizeMiB: 8192,
    Policy:          m.ModificationPolicyRestart,
})
bash
msb modify worker --root-disk 8G --restart
</CodeGroup>

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.