SDK
VM Specs

VM Specs

Whenever you start a sandbox, you can specify which VM specs to use. This allows you to customize the VM to your needs. We also allow you to change the VM specs of a running sandbox on the fly, without reboot. This is useful if you want to dynamically scale up the available hardware based on workload needs.

💡

SDK Sandbox VMTier parameters can be used to create/update environments up to Small (8 Cores/16GB RAM) specs. If higher tiers are specified only the core count will increase unless you create a custom template (opens in a new tab) using our CLI.

Specifying VM Specs when starting your Sandbox

You can start a sandbox with a specific VM tier by passing the vmTier option to the sandbox.create method:

import { CodeSandbox, VMTier } from "@codesandbox/sdk";
 
const sdk = new CodeSandbox();
const sandbox = await sdk.sandboxes.create({
  vmTier: VMTier.Small
});

You can also approximate the VM size:

const sandbox = await sdk.sandboxes.create({
  vmTier: VMTier.fromSpecs({ cpu: 4, memGiB: 8 }),
});

This will pick the smallest VM tier that can fit the specs you provided.

Changing VM Specs

You can change the VM specs of a running sandbox by calling the sandbox.updateTier method:

const sandbox = await sdk.sandboxes.resume('some-id')
 
await sandbox.updateTier(VMTier.Medium);

This will change the VM specs of the sandbox dynamically, without rebooting.

💡

Be careful when scaling down the VM specs of a running sandbox. If you scale down the VM too much, it might not have enough resources to run your tasks and will slow to a crawl.

⚡ Best practices

  • Set appropriate tier when building templates - Choose the minimum VM tier needed for your template's workload and dependencies
  • Don't downgrade from template tier - When creating sandboxes from templates, use the same or higher tier than specified in the template
  • Avoid downgrading running sandboxes - Don't update to a lower tier than the sandbox's initial tier to prevent resource conflicts
HostsOpenTelemetry & Tracing