Scaling

​

How the three interact

• Manual scale() disables autoscale on the sandbox as a side effect — explicit user intent overrides the loop. Re-enable autoscale with setAutoscale({ enabled: true, ... }) after if you want.
• Setting a scaling lock disables autoscale at the same time (single-knob: “I don’t want this scaling, period”). While locked, both scale() and setAutoscale({ enabled: true }) reject with ScalingLockedError. Unlocking does NOT auto-re-enable autoscale.
• Plan caps apply everywhere. Free-tier orgs are capped at 4 GB. Calls above the cap throw PlanLimitError.

​

sandbox.scale(opts)

• ScalingLockedError — sandbox has a scaling lock active.
• PlanLimitError — memoryMB exceeds the org’s plan cap.

import { Sandbox, ScalingLockedError, PlanLimitError } from "@opencomputer/sdk";

const sandbox = await Sandbox.connect("sb-abc123");

try {
  const result = await sandbox.scale({ memoryMB: 8192 });
  console.log(`scaled to ${result.memoryMB}MB / ${result.cpuPercent}% CPU`);
} catch (err) {
  if (err instanceof ScalingLockedError) {
    console.warn("sandbox is locked — unlock to scale");
  } else if (err instanceof PlanLimitError) {
    console.warn("upgrade required for larger instances");
  } else {
    throw err;
  }
}

​

sandbox.setAutoscale(opts)

• ScalingLockedError — sandbox has a scaling lock active.
• PlanLimitError — maxMemoryMB exceeds the org’s plan cap.

• Scale up on a single 1-min sample above 75% memory utilization. Cooldown 60s between up-scales.
• Scale down only when 1-min, 5-min, AND 15-min averages all sit below 25%. Cooldown 5 min between down-scales.

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

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

​

sandbox.getAutoscale()

const cfg = await sandbox.getAutoscale();
if (cfg.enabled) {
  console.log(`autoscale ${cfg.minMemoryMB}–${cfg.maxMemoryMB} MB`);
}

​

sandbox.setScalingLock(locked)

• scale() rejects with ScalingLockedError.
• setAutoscale({ enabled: true }) rejects with ScalingLockedError.
• The platform autoscaler skips this sandbox entirely.

// Pin a sandbox at its current size during a critical workload
await sandbox.setScalingLock(true);

// ...

// Allow scaling again after
await sandbox.setScalingLock(false);

​

sandbox.getScalingLock()

​

Errors

​

ScalingLockedError

import { ScalingLockedError } from "@opencomputer/sdk";

try {
  await sandbox.scale({ memoryMB: 8192 });
} catch (err) {
  if (err instanceof ScalingLockedError) {
    // unlock first, or surface to user
  }
}

​

PlanLimitError