Archive and unarchive sandboxes

Archive a sandbox to keep its filesystem while shutting it down, and unarchive it later to get it back.

This feature is currently in private preview and is not recommended for production use. It requires a feature flag on your workspace: contact us or email [e-mail] to get access. Until then, the archive and unarchive actions are hidden in the Blaxel console, and both API operations answer 403 Forbidden.

Archiving a sandbox stores the filesystem changes it made over its image, then shuts the sandbox down: nothing runs and no memory is kept, and you stop paying for it. The sandbox keeps its name, its configuration, and its preview URLs, so unarchiving gives you the same sandbox back with its files.

Archiving is not a snapshot: memory is not preserved. Processes are stored with their configuration and start again with new IDs when the sandbox is unarchived.

Archive a sandbox

The export runs in the background. By default the SDK waits until the sandbox reaches the ARCHIVED status.

TypeScript

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

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

Archive a sandbox by name, without retrieving it first:

TypeScript

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

await SandboxInstance.archive("my-sandbox");

Unarchive a sandbox

Unarchiving starts the sandbox again from its image and writes the archived filesystem back over it. The sandbox and its terminal answer while the restore runs, and the SDK waits until the sandbox is DEPLOYED again.

TypeScript

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

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

Control the wait

An archive and its restore take longer as the filesystem grows. Pass wait: false in TypeScript, or wait=False in Python, to return as soon as the operation is launched, then read the sandbox status yourself. Set maxWait/max_wait and interval, both in milliseconds, to change how long the SDK waits and how often it reads the sandbox.

TypeScript

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

const sandbox = await SandboxInstance.get("my-sandbox");
await sandbox.archive({ wait: false });

await sandbox.unarchive({ maxWait: 600_000, interval: 5_000 });

Statuses

Status	Meaning
ARCHIVING	The filesystem is being exported and the sandbox is about to be shut down
ARCHIVED	The filesystem is stored and the sandbox is shut down
UNARCHIVING	The sandbox is running again and its archived filesystem is being restored
DEPLOYED	The sandbox is running, and the restore is complete

A sandbox keeps a single archive. Archiving a sandbox again replaces the previous archive, and deleting a sandbox deletes its archive, whatever its status.

Sandbox overview

Learn more about sandbox lifecycle and configuration.

Snapshots and forking

Checkpoint a sandbox, memory included, and fork it into a new one.