Snapshots and fork

Create point-in-time snapshots of sandboxes and fork them into new sandboxes or applications.

Snapshots capture the current state of a sandbox at a point in time. Use snapshots to preserve sandbox state before making changes, or as the basis for forking a sandbox into a new sandbox or application.

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.createSnapshot({ name: "before-migration" });

from blaxel.core import SandboxInstance

sandbox = await SandboxInstance.get("my-sandbox")
snapshot = await sandbox.create_snapshot({"name": "before-migration"})

HTTP API:

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

List snapshots

TypeScript

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

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

from blaxel.core import SandboxInstance

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

HTTP API:

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

Delete a snapshot

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

Fork a sandbox

Forking creates a new resource (sandbox or application) from an existing sandbox. The fork inherits the source sandbox’s image, memory configuration, environment variables, and port settings.

Fork into a new sandbox

TypeScript

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

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

from blaxel.core import SandboxInstance

result = await SandboxInstance.fork("my-sandbox", {
    "target_name": "my-sandbox-copy",
    "target_type": "sandbox",
})

CLI:

bl fork sbx/my-sandbox sbx/my-sandbox-copy

HTTP API:

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

Fork into an application

Create an application directly from a running sandbox. The application inherits the sandbox’s image, memory, environment variables, and port.

TypeScript

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

const result = await SandboxInstance.fork("my-sandbox", {
  targetName: "my-app",
  targetType: "application",
  traffic: 100,
  port: 8080,
});

from blaxel.core import SandboxInstance

result = await SandboxInstance.fork("my-sandbox", {
    "target_name": "my-app",
    "target_type": "application",
    "traffic": 100,
    "port": 8080,
})

CLI:

bl fork sbx/my-sandbox app/my-app --traffic 100 --port 8080

HTTP API:

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

Fork with canary traffic

Fork into an existing application as a canary revision receiving a percentage of traffic:

bl fork sbx/my-sandbox app/my-app --traffic 20 --port 8080

Fork with a custom domain

Attach a custom domain to the forked application using the customDomain parameter:

TypeScript

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

const result = await SandboxInstance.fork("my-sandbox", {
  targetName: "my-app",
  targetType: "application",
  traffic: 100,
  customDomain: "app.example.com",
});

from blaxel.core import SandboxInstance

result = await SandboxInstance.fork("my-sandbox", {
    "target_name": "my-app",
    "target_type": "application",
    "traffic": 100,
    "custom_domain": "app.example.com",
})

HTTP API:

curl -X POST https://api.blaxel.ai/v0/sandboxes/my-sandbox/fork \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: my-workspace" \
  -H "Content-Type: application/json" \
  -d '{
    "targetType": "application",
    "targetName": "my-app",
    "traffic": 100,
    "customDomain": "app.example.com"
  }'

Fork from a snapshot

Use the snapshotId parameter to fork from a specific snapshot instead of the current sandbox state:

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

Fork request parameters

Parameter	Type	Description
targetType	string	Target resource type: sandbox or application
targetName	string	Name of the resource to create or update
traffic	integer	Traffic percentage for the new revision (0-100, applications only)
port	integer	Port to expose
customDomain	string	Custom domain for the application
prefix	string	URL prefix for the application
snapshotId	string	Fork from a specific snapshot instead of current state

Applications

Deploy long-running services with revision management and traffic splitting.

Sandbox overview

Learn more about sandbox lifecycle and configuration.