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.
Live modification is available through TypeScript, Rust, Python, Go, and the CLI. Ruby does not expose a modification API; set its supported options when creating a sandbox.
Supported changes
When a change takes effect depends on the setting:
The default policy applies only changes that can complete without restarting. If a patch contains one restart-required change, microsandbox rejects the whole patch and the old configuration stays intact.
On microsandbox cloud,
modify changes secrets only. A secret’s value, allowed hosts, and removal can apply live; any other secret change applies at the next start, so use the next-start policy, then stop and start the sandbox. The restart policy cannot apply those changes on cloud. On a running sandbox, a live change reads live or fails with a not-confirmed error; it reads next start only when the sandbox is stopped or the next-start policy is used.
Apply changes
This patch doubles the running sandbox’s CPU and memory and updates a label in the same operation:Set resize limits
Live growth needs capacity reserved when the VM boots. Setmax_cpus and max_memory above the starting allocation when you create a sandbox that may need to scale:
Preview changes
Use a dry run when a patch mixes settings or you are unsure whether a restart is needed:Update settings
Resize CPU and memory
msb ps to see allocation as effective / max, and msb metrics to check real usage before resizing. The apply result reports each resource’s resize state, so automation can wait for the guest to settle.
Update labels
Labels are host-side metadata, so adding, changing, or removing one on a running sandbox is applied live by default:msb-metrics tags usage with them from its next collection. With the next_start policy the labels are saved, but metrics and branches keep the old labels until the sandbox starts again.
Sandboxes started by v0.6.3 or earlier can’t apply label changes live; use
--restart or --next-start.Set command defaults
Environment and workdir updates require no restart, but they affect only commands started after the patch:Rotate 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:tls, which needs the same restart or next start. Existing secrets configured with require_tls_identity(false) continue to rotate live over plain HTTP without enabling interception. Removing a secret does not require recreating the sandbox, and on a local sandbox, removing every TLS-dependent secret leaves interception on. See Secrets for sources, host allow lists, and storage behavior.
Grow the root disk
Grow an owned managed or flat ext4 root without restarting, including roots backed by checkpoint layers:--next-start to defer growth or --restart to use stopped growth.
If the disk grows but guest filesystem expansion fails, the error reports incomplete growth. Retry the same target, or stop and restart to finish recovery. Microsandbox never truncates the disk to roll back; snapshots and compaction stay blocked until recovery completes.
Restart required
These changes take effect after a restart:--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.
Change published ports
Add or update one mapping without repeating the others. A mapping is identified by its host address, host port, and protocol. The default is loopback (127.0.0.1) and TCP.
Removal is explicit; an empty list leaves existing mappings unchanged.
--next-start to defer changes or --restart to apply them immediately. Restart preserves disk contents but interrupts processes and connections. Stopped sandboxes save changes for their next start. Use --dry-run to preview changes.
Known port conflicts are rejected before changes are applied, but ports aren’t reserved: binding can still fail at startup and will be logged. Port modification is supported only for local sandboxes.
Reference
For every CLI flag and result state, seemsb modify. The SDK sandbox references expose the same planner and policies for TypeScript, Rust, Python, and Go.