Snapshots and forking

Create point-in-time snapshots of sandboxes, roll them back to a checkpoint, and fork them into new sandboxes.

This feature is currently in private preview and is not recommended for production use.

A snapshot captures the state of a sandbox at a point in time: its filesystem, its running processes, and its memory. Use snapshots to checkpoint a sandbox before a risky change, to roll it back later, or as the basis for forking a new sandbox.

A snapshot outlives the sandbox it was captured from: it stays usable, and forkable, after that sandbox is deleted.

Create a snapshot

Capture a snapshot from the sandbox you want to checkpoint. Snapshot names are unique within a sandbox, and creating a snapshot with a name the sandbox already uses fails with a 409 error. Every snapshot also gets an id, unique across your workspace, which the operations that do not go through the sandbox take instead of the name.

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");
const snapshot = await sandbox.snapshots.create("my-snapshot");

You can also create a snapshot directly through the snapshot API, by passing the name of the sandbox to snapshot as source:

TypeScript

import { Snapshot } from "@blaxel/core";

const snapshot = await Snapshot.create({
  name: "my-snapshot",
  source: { name: "my-sandbox" },
});

POST /sandboxes/{name}/snapshots generates the snapshot name for you, so it cannot collide with an existing one. Use POST /snapshots with a source to choose the name. Sandbox-side operations take the snapshot name, workspace-side operations take snapshot.id.

List snapshots

List from a sandbox to get only the snapshots captured from it:

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");
const snapshots = await sandbox.snapshots.list();

List all your snapshots to also get the ones whose source sandbox no longer exists:

TypeScript

import { Snapshot } from "@blaxel/core";

const snapshots = await Snapshot.list({ limit: 50 });
for await (const snapshot of snapshots) {
  console.log(snapshot.name);
}

The list endpoint is cursor-paginated and supports full-text search on the snapshot name, source name, and status through the q parameter. Refer to the API reference documentation for how to page through the results.

Restore a sandbox to a snapshot

Restoring rolls a sandbox back to one of its own snapshots, in place. The sandbox keeps its name, its URLs, its previews, and its configuration: only the instance behind it is torn down and rebuilt from the snapshot, on the same machine the snapshot was taken on.

Everything the sandbox wrote after the snapshot was taken is lost: files, running processes, and memory state. Take a new snapshot first if you want to be able to come back to the current state.

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");
await sandbox.snapshots.restore("my-snapshot");

The restore returns as soon as it is accepted, without waiting for the sandbox to be back up. The sandbox answers again once its instance has been rebuilt, so retry your first calls while it resumes.

Only a snapshot of that same sandbox can be restored, and only once it is ready. To roll back onto a different sandbox, fork from the snapshot instead.

You can also restore from the Blaxel console: open your sandbox, go to the Snapshots tab, and use the Restore action on the snapshot you want to go back to.

Fork a sandbox

Forking creates a new sandbox from an existing one, forking its entire memory state (files + running processes). The fork inherits the source sandbox’s image, memory configuration, environment variables, and port settings.

Calling fork() automatically snapshots the source sandbox’s current state and forks from it. You don’t need to create a snapshot first.

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");
const result = await sandbox.fork("my-sandbox-copy");

Fork from a snapshot

To create a sandbox from a snapshot you took earlier, pass its name as snapshotId. The fork is created from that snapshot instead of the source sandbox’s current state:

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");
const result = await sandbox.fork("my-sandbox-copy", {
  targetType: "sandbox",
  snapshotId: "my-snapshot",
});

A snapshot carries the image, the memory size, the ports, the infrastructure generation, the region, and the volumes of what it captured, so you can also fork it directly by its id, even after its source sandbox is deleted:

TypeScript

import { Snapshot } from "@blaxel/core";

const snapshot = await Snapshot.get(snapshotId);
const result = await snapshot.fork("my-new-sandbox");

Set targetType to application to start an application from the snapshot instead of a sandbox.

When the source sandbox still exists, the fork also inherits what the snapshot does not carry, such as environment variables, lifecycle policies, and network configuration. When the source sandbox is gone, the fork runs with the configuration stored on the snapshot.

Fork with new environment variables

Pass envs to give the fork a different environment from its source. Each variable the source already carries takes the value you pass, each variable it does not carry is added, and every other variable of the source is inherited. The source sandbox is left untouched.

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");
const result = await sandbox.fork("my-sandbox-copy", {
  envs: [
    { name: "NODE_ENV", value: "staging" },
    { name: "FEATURE_FLAG", value: "1" },
  ],
});

The fork starts with the new environment already applied, so processes you launch in it read the new values. Processes that were already running in the source when it was snapshotted keep the environment they were started with, as an environment change cannot reach a process that is already running.

envs only sets and adds variables. A variable of the source cannot be removed through a fork.

envs works the same way when forking from a snapshot.

Fork with an expiration policy

A fork expires like its source: it inherits the source’s lifecycle expiration policies, along with its ttl and expires. Pass lifecycle to give the fork its own expiration policies instead. The fork is then held to those policies alone, without the source’s ttl or expires. See Sandbox expiration for the available policies.

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");
const result = await sandbox.fork("my-sandbox-copy", {
  lifecycle: {
    expirationPolicies: [
      { type: "ttl-max-age", value: "45m", action: "delete" },
    ],
  },
});

lifecycle works the same way when forking from a snapshot.

Fork request parameters

Parameter	Type	Description
targetType	string	Target resource type: sandbox or application
targetName	string	Name of the resource to create
port	integer	Port to expose
snapshotId	string	Name of the snapshot to fork from, instead of the current state
envs	array	Environment variables the fork runs with, on top of the ones inherited from the source
lifecycle	object	Expiration policies of the fork, instead of the ones inherited from the source. Takes expirationPolicies, like the sandbox’s lifecycle

Delete a snapshot

Delete a snapshot by its name from the sandbox it was captured from:

TypeScript

import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");
await sandbox.snapshots.delete("my-snapshot");

Or by its id, which also works once the sandbox is deleted:

TypeScript

import { Snapshot } from "@blaxel/core";

await Snapshot.delete(snapshotId);

Deleting a snapshot is the only thing that removes it. Snapshots have no expiration, and Blaxel never prunes them for you.

Snapshots and sandbox deletion

Deleting a sandbox does not delete its snapshots. They keep their names and stay forkable, with source.deleted set to true to tell you their sandbox is gone.

Snapshots keep consuming storage after their source sandbox is deleted, and they count against your workspace snapshot quota. Delete the snapshots you no longer need. Refer to quotas for the limits that apply to your workspace.

Archive a sandbox

Keep a sandbox’s filesystem while shutting it down, and get it back later.

Sandbox overview

Learn more about sandbox lifecycle and configuration.