How Microsandbox Manages Memory Within the Sandbox: A Deep Dive Into Guest Memory Allocation

Microsandbox manages guest memory through a configurable, declarative specification system using memory_mib and max_memory_mib fields, with support for live resizing via control sockets when available.

Understanding how microsandbox manages memory within the sandbox is essential for optimizing workload performance and resource utilization. The microsandbox project (superradcompany/microsandbox) implements a flexible memory model that balances immediate configuration with runtime adaptability. This article examines the complete memory management pipeline from the Rust SDK builder API through to VM hypervisor configuration.

Memory Specification in the Sandbox Resources

Every microsandbox defines its memory characteristics in the resources section of its specification. Two key fields control guest memory allocation:

• memory_mib — The amount of memory allocated to the guest at boot time
• max_memory_mib — The upper bound for hot-pluggable memory that the guest may grow to during execution

These values work in tandem to provide both predictable startup behavior and runtime flexibility.

Builder API for Memory Configuration

The Rust SDK exposes fluent methods on SandboxModificationBuilder that populate a SandboxModificationPatch with desired memory values. In sdk/rust/lib/sandbox/modify.rs, the memory and max_memory methods handle this assignment:

// Set the effective guest memory (MiB)
.memory(512)                // ← stores in `patch.memory_mib`
// Set the maximum hot-pluggable memory (MiB)
.max_memory(1024)           // ← stores in `patch.max_memory_mib`

View implementation

The SandboxModificationPatch struct carries these values through the planning stage, holding both memory_mib and max_memory_mib fields that drive subsequent runtime decisions.

Live Control vs. Restart-Required Application

When memory modifications are applied, the builder produces a SandboxModificationPlan that determines how changes take effect.

Live Memory Resizing

If the running sandbox advertises live control for memory (LiveControl::resize == true), the plan sends a JSON control message over the control socket:

{ "op": "memory_target", "total_mib": <value> }

The runtime forwards this request to the VM hypervisor, which adjusts the guest-visible memory size without restart. The control_memory_target helper in crates/agentd/lib/lib.rs builds this payload:

View control_memory_target implementation

Restart-Required Fallback

When live control is unavailable (the default on current runtimes), the plan marks the change as restart-required. The next sandbox launch passes memory_mib to the VM configuration, and the guest starts with the new size.

Memory Back-Ends and Consumption

Microsandbox's memory model encompasses multiple consumption mechanisms:

Root-Disk Overlay (tmpfs)

The root_disk_size parameter configures a RAM-backed filesystem whose size directly consumes guest memory. This overlay storage competes for the same memory budget as the guest's working set.

Hot-Plug Capability

When max_memory_mib exceeds memory_mib, the runtime may expose additional RAM that the guest can request at runtime—typically via balloon devices. This capability requires live-control support to be functional.

Safety Validation for Memory Configuration

The modification logic enforces consistency through validation in sdk/rust/lib/sandbox/modify.rs:

1. max_memory_mib must be ≥ memory_mib — The system automatically upgrades max_memory_mib to match if underspecified
2. Requested size cannot exceed active maximum — An error is reported if memory_mib exceeds max_memory_mib

View validation block

Practical Code Examples

Creating a Sandboxed Workload with Memory Limits

use microsandbox::sandbox::SandboxBuilder;

// Create a sandbox that starts with 512 MiB of RAM
let sb = SandboxBuilder::new("demo")
    .memory(512)               // effective memory at boot
    .max_memory(1024)          // allow hot-plug up to 1 GiB
    .build()?;

// Later, resize the running sandbox (if live control is available)
sb.modify()
    .memory(768)               // raise to 768 MiB
    .apply()?;                 // will either send a live op or schedule a restart

CLI-Based Memory Modification

# Using the CLI (msb) to adjust memory on an existing sandbox

$ msb modify my-sandbox --memory 1024 --max-memory 2048

Key Implementation Files

Component	File	Purpose
SDK Builder API	sdk/rust/lib/sandbox/modify.rs — memory, max_memory methods	Public API for memory configuration
Patch Definition	sdk/rust/lib/sandbox/modify.rs — SandboxModificationPatch struct	Carries memory values through planning
Live Control	crates/agentd/lib/lib.rs — control_memory_target	Implements live-resize protocol
Validation	sdk/rust/lib/sandbox/modify.rs — validation block	Ensures safe memory configuration
VM Configuration	crates/agentd/lib/config.rs	Applies memory to VM launch arguments

Summary

• Declarative specification — Memory is defined via memory_mib and max_memory_mib in sandbox resources
• Builder API pattern — SandboxModificationBuilder provides fluent configuration methods
• Dual application modes — Live control enables runtime resizing; otherwise changes apply on restart
• Safety guarantees — Validation ensures max_memory_mib ≥ memory_mib and prevents oversubscription
• Hot-plug foundation — Separation of current and maximum memory enables future balloon device integration

Frequently Asked Questions

What happens if I request more memory than max_memory_mib allows?

The validation logic in modify.rs reports an error. The system prevents any configuration where the requested memory_mib exceeds the configured max_memory_mib ceiling.

Can I resize memory without restarting my sandbox?

Only if the runtime supports live control. Check LiveControl::resize on your running sandbox. When true, the memory_target JSON operation is sent via control socket for immediate hypervisor adjustment.

How does root_disk_size relate to memory management?

The root_disk_size parameter creates a tmpfs-backed overlay that consumes guest memory directly. Size this parameter conservatively to leave adequate memory for your workload's actual operations.

What is the default behavior for memory modifications on current runtimes?

Most current runtimes default to restart-required application. The modification plan detects lack of live control and schedules the change for the next sandbox launch rather than attempting immediate resize.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}