Snapshots

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. Snapshots are workspace resources of their own, so a snapshot stays available after you delete the sandbox it was captured from, and it carries everything needed to create a new sandbox or application from it. Use snapshots to checkpoint a sandbox before a risky change, to keep a warm starting point for new sandboxes, or to keep a template of a fully booted environment long after the sandbox that produced it is gone.

Snapshot identity

A snapshot has a name that is unique in your workspace and that every operation addresses it by. Pick the name at creation time, or let Blaxel generate one:

Field	Description
`name`	Workspace-unique name you address the snapshot by. Generated when you do not pass one
`id`	Internal identifier of the stored snapshot. Read-only, and usable anywhere a snapshot name is expected
`source`	Object the snapshot was captured from: `name`, `kind` (`sandbox`), and `deleted`
`spec`	Configuration a fork runs with: `image`, `memory`, `ports`, `generation`, `region`, and `volumes`
`status`	`ready` once the snapshot can be forked or restored
`createdAt`	When the snapshot was captured

Creating a snapshot with a name that is already taken in the workspace fails with a 409 error. Delete the existing snapshot first, or pick another name.

Create a snapshot

A snapshot always has a source. Pass the name of the object to capture as source, and a name if you want to choose it:

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

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

from blaxel.core import Snapshot

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

curl -X POST https://api.blaxel.ai/v0/snapshots \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: my-workspace" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-snapshot",
    "source": { "name": "my-sandbox" }
  }'

You can also capture a snapshot from the sandbox itself, which is the same operation with the source filled in for you:

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

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

from blaxel.core import SandboxInstance

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

source.kind defaults to sandbox, the only kind of object you can capture today.

Retrieve a snapshot

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

const snapshot = await Snapshot.get("my-snapshot");
console.log(snapshot.source.name, snapshot.source.deleted);

from blaxel.core import Snapshot

snapshot = await Snapshot.get("my-snapshot")
print(snapshot.source.name, snapshot.source.deleted)

curl https://api.blaxel.ai/v0/snapshots/my-snapshot \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: my-workspace"

List snapshots

Listing at the workspace level returns every snapshot, including the ones whose source sandbox no longer exists.

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

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

import asyncio
from blaxel.core import Snapshot

async def main():
    snapshots = await Snapshot.list(limit=50)
    async for snapshot in snapshots.auto_paging_iter():
        print(snapshot.name)

asyncio.run(main())

bl get snapshots

The list endpoint is cursor-paginated and supports full-text search on the snapshot name, source name, and status through the q parameter:

curl 'https://api.blaxel.ai/v0/snapshots?limit=50&q=my-snapshot' \
  -H 'X-Blaxel-Authorization: Bearer YOUR-API-KEY' \
  -H 'Blaxel-Version: 2026-04-28'

Pass meta.nextCursor as cursor on the next request and repeat until meta.hasMore is false. For more information, refer to the API reference documentation. To list only the snapshots captured from one sandbox, list from the sandbox instead:

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

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

from blaxel.core import SandboxInstance

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

curl https://api.blaxel.ai/v0/sandboxes/my-sandbox/snapshots \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: my-workspace"

Fork a snapshot into a new sandbox

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 fork it into a new sandbox even after its source sandbox is deleted.

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

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

from blaxel.core import Snapshot

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

curl -X POST https://api.blaxel.ai/v0/snapshots/my-snapshot/fork \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: my-workspace" \
  -H "Content-Type: application/json" \
  -d '{
    "targetType": "sandbox",
    "targetName": "my-new-sandbox"
  }'

Set targetType to application to start an application from the snapshot instead of a sandbox, and pass envs to give the fork a different environment. Both work the same way as when forking 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.

Restore a sandbox to a snapshot

Restoring rolls a running sandbox back to a snapshot in place, keeping its name, its URLs, and its previews. Refer to restoring a sandbox for the full behavior.

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

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

from blaxel.core import SandboxInstance

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

curl -X POST https://api.blaxel.ai/v0/sandboxes/my-sandbox/snapshots/my-snapshot/restore \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: my-workspace"

Delete a snapshot

There is a single snapshot object, so deleting it removes it for the whole workspace. Deleting it from the sandbox it was captured from does the same thing.

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

await Snapshot.delete("my-snapshot");

from blaxel.core import Snapshot

await Snapshot.delete("my-snapshot")

curl -X DELETE https://api.blaxel.ai/v0/snapshots/my-snapshot \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: my-workspace"

bl delete snapshot my-snapshot

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

Snapshot lifecycle and sandbox deletion

Deleting a sandbox does not delete its snapshots. The snapshots stay in your workspace, keep their names, and stay usable. The only visible change is on the link back to the source, whose deleted field becomes true:

{
  "name": "my-snapshot",
  "status": "ready",
  "source": {
    "kind": "sandbox",
    "name": "my-sandbox",
    "deleted": true
  }
}

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.

Snapshots and forking for sandboxes

Snapshot, restore, and fork from the sandbox side.

Sandbox overview

Learn more about sandbox lifecycle and configuration.

Get Started

Sandboxes

Agent Drive

Volumes

Batch Jobs

Applications

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

Troubleshooting

Snapshots

Snapshot identity

Create a snapshot

Retrieve a snapshot

List snapshots

Fork a snapshot into a new sandbox

Restore a sandbox to a snapshot

Delete a snapshot

Snapshot lifecycle and sandbox deletion

Snapshots and forking for sandboxes

Sandbox overview

​Snapshot identity

​Create a snapshot

​Retrieve a snapshot

​List snapshots

​Fork a snapshot into a new sandbox

​Restore a sandbox to a snapshot

​Delete a snapshot

​Snapshot lifecycle and sandbox deletion

Snapshots and forking for sandboxes

Sandbox overview

Snapshot identity

Create a snapshot

Retrieve a snapshot

List snapshots

Fork a snapshot into a new sandbox

Restore a sandbox to a snapshot

Delete a snapshot

Snapshot lifecycle and sandbox deletion