POSTEngineering log
Give Your AI Agent Room for Memory Spikes
- Written by
- Sandbox0 Team
Your agent has cloned a repository, installed its tools, and spent time making a change. Then a build or test run needs more memory than the rest of the session. Hitting the memory limit at that point can interrupt useful work.
Sizing every sandbox for its largest possible task gives you more room, but also means paying for that larger memory limit throughout its running time. For agents with occasional peaks, a smaller everyday allocation with some extra room can be a better fit.
Sandbox0 memory burst lets you authorize up to 50% additional memory when you create a sandbox. A sandbox with a 4 GiB base can start at 4 GiB, expand to 6 GiB as memory pressure rises, and return to 4 GiB when it is safe. The automatic changes keep the same processes running. CPU stays at the base specification, and compute billing follows the memory limit actually in effect.
Memory burst is available in ali-ue1 and is optional for each sandbox.
Existing sandboxes do not automatically opt in.
Keep the Usual Size, Allow for the Busy Part#
An agent's memory needs can change from one step to the next. Reading code may need little memory; running a build, opening several browser tabs, or processing a larger file can need much more. Burst is useful when the base size fits the regular workload and those heavier steps are occasional.
With a 4 GiB base and a 50% allowance, the experience looks like this:
| Part of the session | Memory limit | What happens to the agent |
|---|---|---|
| Normal work | 4 GiB | The agent runs at its base size. |
| Memory pressure rises | Up to 6 GiB | Sandbox0 can expand the limit without restarting the agent. |
| The heavy step finishes | 6 GiB until safe to shrink, then 4 GiB | The same agent keeps working as the limit returns to base. |
You authorize the larger ceiling once. Your application does not need to detect each peak and send a resize request. Expansion begins before the base limit is exhausted, subject to available capacity and timely observations.
Returning to base is deliberately cautious. If the agent still has 5 GiB of live memory, the sandbox stays at 6 GiB. There is no countdown that forces it back into 4 GiB and kills processes. Even after memory is released, shrinking waits for sustained low usage and a safety check.
Pay for the Limit in Effect#
Enabling a 6 GiB ceiling does not make the sandbox billable at 6 GiB for its entire session. Compute usage follows the applied limit:
- Before expansion, the sandbox is billed at 4 GiB.
- While expanded, it is billed at 6 GiB.
- After it safely returns to base, it is billed at 4 GiB again.
This is limit-based billing. If your processes use 2 GiB while the applied limit is 4 GiB, the billable size is still 4 GiB. Likewise, releasing memory does not lower the billable size until the limit has actually shrunk.
For an illustrative hour with 50 minutes at a 4 GiB limit and 10 minutes at a 6 GiB limit, compute usage is:
text(4 GiB × 50/60 hours) + (6 GiB × 10/60 hours) = 4⅓ GiB-hours
Multiply that usage by the current compute rate. The ten minutes include all time the higher limit remains in effect, including the wait to shrink. This example is a billing illustration, not a promise about how long your workload will stay expanded. Pausing still stops compute charges; retained storage follows its separate pricing rules.
Enable It When You Create the Sandbox#
Choose a base that comfortably fits normal work, then set the percentage of additional memory you are willing to authorize. In the CLI:
bashs0 sandbox create --template default \ --api-url https://ali-ue1.sandbox0.ai \ --memory 4Gi --memory-burst-percent 50
Or use the JavaScript/TypeScript SDK:
typescriptimport { Client } from "sandbox0"; const client = new Client({ token: process.env.SANDBOX0_TOKEN!, baseUrl: "https://ali-ue1.sandbox0.ai", }); const sandbox = await client.sandboxes.claim("default", { memory: "4Gi", config: { resources: { memoryBurstPercent: 50 } }, });
Use CLI v0.10.6 or JavaScript/TypeScript SDK v0.10.8, or newer.
Go and Python support are available in v0.10.6 of their respective SDKs.
The HTTP API field is config.resources.memory_burst_percent; SDKs use their
language's naming conventions. See the resource configuration guide
for the API contract.
Omitting the percentage, or setting it to 0, leaves burst disabled. The
allowance can be at most 50%, and the base plus allowance must fit the platform's
maximum sandbox memory. Both examples target the supported ali-ue1 region.
When to Choose a Larger Base Instead#
Burst provides headroom for variation. A workload that routinely needs 5 GiB should have a base sized for that working set. Otherwise it may spend much of its time expanded, and the bill will reflect that higher limit.
There are a few other boundaries to keep in mind:
- Extra memory does not add CPU. If a build needs more processing capacity, choose an appropriate base specification rather than expecting burst to accelerate it.
- The allowance is permission, not reserved RAM. Expansion depends on worker capacity. A sudden large allocation can also reach the current limit before expansion takes effect, so burst cannot guarantee that every out-of-memory failure will be avoided.
- Automatic burst differs from editing a sandbox's resources. Explicitly changing its base memory or burst percentage uses the resource-update flow, which restarts processes and discards retained process checkpoints. Configure the allowance at creation when you want automatic changes during a session.
- A memory-preserving resume starts at the authorized ceiling. This gives captured pages room to return. It is billed at that ceiling until it can safely shrink. Ordinary filesystem-only pause/resume does not preserve process memory; see pause and resume.
Start with an agent workload whose normal memory needs you already understand. Enable burst for the occasional heavier step, observe how long it stays above base, and adjust the base size if peaks become the everyday workload.
Create a sandbox, or read the memory burst guide to add the option to your next agent session.
See also
- AI Sandbox Pricing: Compute, Storage, and Paused Time
Plan running compute costs and understand what happens to your bill when you pause.
- Initialize Once, Claim Many: Custom AI Agent Sandboxes on Sandbox0
Prepare reusable environments before your agents start working.