Create Sandbox

Sandboxes are the main building blocks of the CodeSandbox SDK. Each one represents a single project that you can run, fork, and modify.

Every Sandbox is backed by a Firecracker VM, and is completely isolated and persisted. Providing you with a secure environment to run untrusted code.

Creating a Sandbox

To create a sandbox, call sandbox.create():

import { CodeSandbox } from '@codesandbox/sdk'
 
const sdk = new CodeSandbox();
const sandbox = await sdk.sandboxes.create();

💡

By default Sandboxes are unlisted and can be accessed and forked by anyone with a url. If you want to create a private sandbox you can pass privacy: 'private', which requires host tokens to access the exposed ports.

If no id option is provided to sandbox.create(), we'll create a sandbox forked from our Universal (opens in a new tab) template on CodeSandbox. You can also pass in a specific template id from our collection of templates or by creating your own template using our Template Builder.

const sandbox = await sdk.sandboxes.create({
    id: 'some-sandbox-id',
 
    // Optional properties
    title: 'my-sandbox',
    description: 'My sandbox',
    tags: ['my-tag'],
 
    // Public, unlisted or private
    privacy: 'private',
 
    // Collection folder on Dashboard
    path: '/users/some-user-folder',
 
    // Prefer closest cluster. Follows ISO 3166-1 alpha-2 codes.
    ipcountry: "US",
 
    // What VM Tier to use for the Sandbox
    vmTier: VMTier.Pico,
 
    // How quickly the sandbox should hibernate after inactivity.
    // Defaults to 300 seconds for free users, 1800 seconds for
    // pro users. Maximum is 86400 seconds (1 day).
    hibernationTimeoutSeconds: 120_000,
 
    // Configure if Sandbox should wake up automatically on HTTP
    // or requests or WebSocket connections
    automaticWakeupConfig: {
        http: true,
        websocket: true
    }
})

💡

The automaticWakeupConfig only wakes up the Sandbox, it does not extend its hibernation timeout.

Resume an Existing Sandbox

To resume an existing sandbox from hibernation and connect to it call: sdk.sandboxes.resume(id):

const sandbox = await sdk.sandboxes.resume('sandbox-id');

💡

Sandboxes that have been dormant for a week will do a CLEAN bootup, meaning it will run its setup tasks when resumed. Please make sure you handle this case in your application.

Sandbox Properties

The sandbox object represents the instance of a sandbox running in our infrastructure. The methods detailed below require the Sandbox to be running.

Each Sandbox has the following properties, with information about it's own instance:

id: The unique identifier of the sandbox.
isUpToDate: Whether the sandbox is up to date with the latest agent version.
cluster: The cluster the sandbox is running on.
bootupType: The type of bootup, RUNNING, CLEAN, RESUME or FORK.

Snapshots

When a Sandbox is hibernated, we create and save a snapshot of the underlying Firecracker VM.

If you call sdk.sandboxes.resume(id) or a network request is made to the Sandbox, we restore the snapshot. Allowing you to continue from exactly where you left off.

As we already have a snapshot, we can also use it to create a fork of your project in a new Sandbox. So you can create multiple instances without having to do all the set up work every time.

import { CodeSandbox } from '@codesandbox/sdk'
const sdk = new CodeSandbox();
 
const sandbox = await sdk.sandboxes.create();
const client = await sandbox.connect()
 
// Run anything on the sandbox
await client.shells.run('echo test > test.txt');
 
const sandbox2 = await sdk.sandboxes.create({
    id: sandbox.id
});
 
// Now we have two sandboxes that have the same fs & memory state!

You can use this to add support for checkpoint/restore functionality, or A/B test different agent iterations. At CodeSandbox we use this to enable users to quickly fork shared Sandboxes to their own account.

Manually Creating a Snapshot

import { CodeSandbox } from '@codesandbox/sdk'
 
const sdk = new CodeSandbox();
const sandbox = await sdk.sandboxes.create();
 
// Do work
 
await sdk.sandboxes.hibernate(sandbox.id);

Creating a snapshot can take between 3-10 seconds. Resuming from a snapshot takes between 0.5-2 seconds.

Live snapshots

If a Sandbox is already running we can still fork its exact current state. This has a small overhead of about 0.5 seconds.

Learn More

We have written a couple blog posts about how snapshots work under the hood:

Docker & Docker Compose Update Sandbox