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

> Learn how microsandbox manages guest memory with declarative settings like memory_mib and max_memory_mib. Explore live resizing options via control sockets for dynamic memory allocation.

- Repository: [Super Rad Company/microsandbox](https://github.com/superradcompany/microsandbox)
- Tags: deep-dive
- Published: 2026-08-20

---

**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`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/modify.rs), the `memory` and `max_memory` methods handle this assignment:

```rust
// 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](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/modify.rs#L27-L45)

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:

```json
{ "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`](https://github.com/superradcompany/microsandbox/blob/main/crates/agentd/lib/lib.rs) builds this payload:

[View control_memory_target implementation](https://github.com/superradcompany/microsandbox/blob/main/crates/agentd/lib/lib.rs#L784-L795)

### 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`](https://github.com/superradcompany/microsandbox/blob/main/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](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/modify.rs#L1336-L1351)

## Practical Code Examples

### Creating a Sandboxed Workload with Memory Limits

```rust
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

```bash

# 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`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/modify.rs) — `memory`, `max_memory` methods | Public API for memory configuration |
| Patch Definition | [`sdk/rust/lib/sandbox/modify.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/modify.rs) — `SandboxModificationPatch` struct | Carries memory values through planning |
| Live Control | [`crates/agentd/lib/lib.rs`](https://github.com/superradcompany/microsandbox/blob/main/crates/agentd/lib/lib.rs) — `control_memory_target` | Implements live-resize protocol |
| Validation | [`sdk/rust/lib/sandbox/modify.rs`](https://github.com/superradcompany/microsandbox/blob/main/sdk/rust/lib/sandbox/modify.rs) — validation block | Ensures safe memory configuration |
| VM Configuration | [`crates/agentd/lib/config.rs`](https://github.com/superradcompany/microsandbox/blob/main/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`](https://github.com/superradcompany/microsandbox/blob/main/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.