SDK
Introduction

CodeSandbox SDK

Programmatically spin up (AI) sandboxes

CodeSandbox SDK (beta) enables you to quickly create and run isolated sandboxes securely. The SDK can be used to run concurrent VMs to support multiple use cases such as AI agents, code interpretation and more

How it works

The SDK can spin up a sandbox by cloning a template in under 3 seconds. Inside this VM, you can run any code, install any dependencies and even run servers.

The sandboxes run on the same infrastructure as CodeSandbox, which means you can clone, snapshot and restore sandboxes at any point in time (checkpointing).

Under the hood, the SDK uses the microVM infrastructure of CodeSandbox to spin up sandboxes. It supports:

  1. Memory snapshot/restore (checkpointing) at any point in time
  2. Resume/clone VMs from a snapshot in 3 seconds
  3. VM FS persistence (with git version control)
  4. Environment customization using Docker & Docker Compose (Dev Containers)

Quickstart

Install the SDK:

npm install @codesandbox/sdk

Create an API key at https://codesandbox.io/t/api (opens in a new tab), and enable all scopes.

Now you can create a sandbox and run a server:

import { CodeSandbox } from "@codesandbox/sdk";
 
const sdk = new CodeSandbox(process.env.CSB_API_KEY!);
const sandbox = await sdk.sandbox.create();
 
await sandbox.shells.python.run("print(1+1)");
await sandbox.shells.run('echo "Hello World"');
 
// We can also start shells in the background by not awaiting them
const shellInfo = sandbox.shells.run("npx -y serve .");
 
// Wait for port to open
const portInfo = await sandbox.ports.waitForPort(3000);
console.log(portInfo.getPreviewUrl());
 
// And, we can clone(!) the sandbox! This takes 1-3s.
const sandbox2 = await sandbox.fork();
 
// Sandbox 2 will have the same processes running as sandbox 1
const portInfo2 = await sandbox2.ports.waitForPort(3000);
console.log(portInfo2.getPreviewUrl());
 
// Finally, we can hibernate the sandbox. This will snapshot the sandbox and stop it.
// Next time you start the sandbox, it will continue where it left off, as we created a memory snapshot.
// The sandboxes will also automatically resume if a network request comes in for the
// servers they have started.
await sandbox.hibernate();
await sandbox2.hibernate();
 
// Open the sandbox again
const resumedSandbox = await sdk.sandbox.open(sandbox.id);
Use Cases