Elasticity

A sandbox's memory and CPU can be resized at runtime. The platform's recommended path is Autoscaling — opt the sandbox in once and we resize it for you based on observed memory pressure. Lower-level controls are also available if you want to drive sizing yourself or freeze it.

CPU scales proportionally to memory in all modes (1 vCPU per ~4 GB up to 16 GB / 4 vCPU). The permissible memory tiers are:

Memory	vCPU
1 GB	1 (best-effort)
4 GB	1
8 GB	2
16 GB	4

If you want a sandbox to stay at a fixed size, see Locking Resources.

Ask AI about this page

Autoscaling

Opt a sandbox into the per-sandbox autoscaler and the platform resizes it for you based on observed memory pressure. Autoscale is opt-in per sandbox and disabled by default.

This is the recommended way to size a sandbox: turn it on once with bounds you're comfortable with, then leave it. Manual scale and the in-VM API are escape hatches for cases where the autoscaler isn't a good fit (e.g. you want a hard guarantee for a benchmark, or you're scripting your own logic).

Enable

typescript

12345await sandbox.setAutoscale({
  enabled: true,
  minMemoryMB: 1024,
  maxMemoryMB: 16384,
});

minMemoryMB and maxMemoryMB must be values from the tier table above. The autoscaler keeps the sandbox between these bounds, in tier steps.

Behavior

Scale up: when the sandbox's 1-minute average memory utilization exceeds 75 %, jump to the next tier. 60-second cooldown between up-events.
Scale down: when all of the 1-min, 5-min, and 15-min utilization averages stay below 25 %, drop one tier. 5-minute cooldown between down-events. Down requires at least 15 minutes of low-utilization data, so a brief idle pause won't shrink you.
Manual override: any explicit scale call disables autoscale on that sandbox. Re-enable explicitly via setAutoscale({ enabled: true, ... }) (or the equivalent in any SDK) if you want it back.

Disable

typescript

1await sandbox.setAutoscale({ enabled: false });

Inspect

typescript

12const cfg = await sandbox.getAutoscale();
// { sandboxID: "sb-...", enabled: true, minMemoryMB: 1024, maxMemoryMB: 16384 }

Manual Scaling (Control Plane)

When you want to resize once — predictable size for a benchmark, a one-off scale-up before a known-heavy task, an operator response to an alert — call scale from your application or operator tooling:

typescript

1await sandbox.scale({ memoryMB: 4096 });

A manual scale disables autoscale on the sandbox — explicit user intent overrides the loop. Re-enable it later if you want size to track load again.

The endpoint can return:

403 scaling_locked — the sandbox is locked. See Locking Resources.
409 oom_floor — the requested size would force a guest OOM-kill because the current working set exceeds it. Free memory inside the guest, then retry.
402 Payment Required — the requested size exceeds your plan cap.

In-VM Scaling

Sandboxes expose an internal metadata API at http://169.254.169.254 that lets code inside the VM scale itself. Useful for workload-aware scripts where the workload knows its own demand better than the platform autoscaler can infer (e.g. "scale up before this build, back down after").

This endpoint is only reachable from inside the sandbox. It is not exposed through the control plane API or SDKs.

Scale Memory

Send a POST to /v1/scale with the desired memory in MB. CPU is adjusted proportionally.

bash

123curl -s -X POST http://169.254.169.254/v1/scale \
  -H "Content-Type: application/json" \
  -d '{"memoryMB": 4096}'

Check Current Limits

bash

1curl -s http://169.254.169.254/v1/limits

Example: Rust Compilation

Rust builds are memory-hungry. You can alias cargo to scale up before compilation and scale back down after:

bash

12345678910111213141516alias cargo='_cargo_scaled'
_cargo_scaled() {
  # Scale up to 16GB / 4 vCPU before build
  curl -sf -X POST http://169.254.169.254/v1/scale \
    -H "Content-Type: application/json" -d '{"memoryMB": 16384}'

  # Run the actual cargo command
  command cargo "$@"
  local exit_code=$?

  # Scale back down to 4GB / 1 vCPU
  curl -sf -X POST http://169.254.169.254/v1/scale \
    -H "Content-Type: application/json" -d '{"memoryMB": 4096}'

  return $exit_code
}

Add this to your sandbox's ~/.bashrc or inject it via sandbox.exec.run so every cargo build, cargo test, etc. automatically gets the extra resources.

Example: Custom Scaling Loop

A simple shell script that monitors memory pressure and scales automatically. Useful when you want fine-grained control inside the sandbox itself; for the platform-managed equivalent see Autoscaling above.

bash

1234567891011121314151617181920212223242526272829303132333435363738394041#!/bin/sh
SCALE_API="http://169.254.169.254/v1/scale"
MIN_MB=1024
MAX_MB=8192
SCALE_UP_THRESHOLD=80
SCALE_DOWN_THRESHOLD=30
COOLDOWN=30
last_scale=0

while true; do
  mem_total=$(awk '/MemTotal/{print $2}' /proc/meminfo)
  mem_avail=$(awk '/MemAvailable/{print $2}' /proc/meminfo)
  usage_pct=$(( (mem_total - mem_avail) * 100 / mem_total ))
  total_mb=$((mem_total / 1024))
  now=$(date +%s)
  elapsed=$((now - last_scale))

  if [ $usage_pct -gt $SCALE_UP_THRESHOLD ] && [ $elapsed -gt $COOLDOWN ]; then
    new_mb=$((total_mb * 2))
    [ $new_mb -gt $MAX_MB ] && new_mb=$MAX_MB
    if [ $new_mb -gt $total_mb ]; then
      echo "usage=$usage_pct% -> scaling UP to ${new_mb}MB"
      curl -sf -X POST "$SCALE_API" \
        -H "Content-Type: application/json" \
        -d "{\"memoryMB\":$new_mb}"
      last_scale=$now
    fi
  elif [ $usage_pct -lt $SCALE_DOWN_THRESHOLD ] && [ $total_mb -gt $MIN_MB ] && [ $elapsed -gt $COOLDOWN ]; then
    new_mb=$((total_mb / 2))
    [ $new_mb -lt $MIN_MB ] && new_mb=$MIN_MB
    if [ $new_mb -lt $total_mb ]; then
      echo "usage=$usage_pct% -> scaling DOWN to ${new_mb}MB"
      curl -sf -X POST "$SCALE_API" \
        -H "Content-Type: application/json" \
        -d "{\"memoryMB\":$new_mb}"
      last_scale=$now
    fi
  fi

  sleep 5
done

Locking Resources

If you want a sandbox to stay at a fixed size — predictable billing, a benchmark, a long-running pinned workload — lock it. Locking blocks both manual scaling and autoscaling on the sandbox.

typescript

1await sandbox.setScalingLock(true);

While locked:

scale returns 403 scaling_locked
setAutoscale({ enabled: true }) returns 403 scaling_locked
The autoscaler skips the sandbox

Locking automatically disables autoscale on the sandbox, so you have a single user-facing toggle. Unlocking does not auto-re-enable autoscale; turn it back on explicitly if you want it.

typescript

123456// Unlock
await sandbox.setScalingLock(false);

// Inspect
const lock = await sandbox.getScalingLock();
// { sandboxID: "sb-...", locked: false }