Snapshots and forking

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

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

Snapshots capture the current state of a sandbox at a point in time. Use snapshots to checkpoint sandbox state to allow rollbacks after making changes, or as the basis for forking a sandbox into a new sandbox.

Create a snapshot

Create a snapshot of an existing sandbox. The snapshot captures the filesystem, running processes, and memory state.

TypeScript

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

const sandbox = await SandboxInstance.get("my-sandbox");
const snapshot = await sandbox.snapshot("before-migration");

List snapshots

TypeScript

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

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

Delete a snapshot

TypeScript

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

const sandbox = await SandboxInstance.get("my-sandbox");
await sandbox.deleteSnapshot("snap_abc123");

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.restore("snap_abc123");

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 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: "snap_abc123",
});

Fork request parameters

Parameter	Type	Description
targetType	string	Target resource type: sandbox
targetName	string	Name of the sandbox to create
port	integer	Port to expose
snapshotId	string	Fork from a specific snapshot instead of current state

Sandbox overview

Learn more about sandbox lifecycle and configuration.