Archive and unarchive sandboxes

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 support@blaxel.ai 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.

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

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

from blaxel.core import SandboxInstance

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

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

Archive a sandbox by name, without retrieving it first:

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

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

from blaxel.core import SandboxInstance

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.

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

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

from blaxel.core import SandboxInstance

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

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

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.

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 });

from blaxel.core import SandboxInstance

sandbox = await SandboxInstance.get("my-sandbox")
await sandbox.archive(wait=False)

await sandbox.unarchive(max_wait=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.

Archive to your own storage

Everything above uses storage managed by Blaxel. The sandbox API that produces those archives is also reachable directly, so you can write the same archive to a bucket you own and restore it into a sandbox later. Use it to keep backups outside Blaxel, to copy a filesystem between workspaces or regions, or to keep several archives of the same sandbox. The sandbox never holds your storage credentials. You presign the upload or the download yourself, and hand the sandbox the resulting URL. A presigned URL carries a signature made with your own credentials, granting one request on one object for a limited time — so the sandbox can write or read that single object and nothing else. Call these endpoints on the sandbox’s own URL, available as sandbox.metadata.url in the SDKs, with the same authentication as any other sandbox API call.

An export stops the workload and freezes the filesystem, and the freeze is not lifted when the export finishes. Treat a sandbox you exported yourself as done, or call POST /archive/resume to use it again.

Archive contents

An archive is an uncompressed tar of everything the sandbox changed on top of the image it booted from, plus a metadata directory:

Member	Content
`.blaxel-archive/manifest.json`	What the archive holds and what it was taken from
`.blaxel-archive/processes.json`	The processes that were running, so a restore can start them again
Everything else	One member per added or modified path, relative to `/`, with its mode, ownership and modification time

Deleted paths cannot travel as tar members, so they are listed in the manifest under deleted and applied by the restore.

manifest.json

{
  "version": 1,
  "createdAt": "2026-08-27T09:12:44Z",
  "apiVersion": "v0.1.0",
  "imageDevice": "/dev/vda",
  "root": "/",
  "excludes": [
    "proc", "sys", "dev", "run", "tmp", "mnt",
    "etc/resolv.conf", "etc/hostname", "etc/hosts",
    "run/secrets", "var/run/secrets"
  ],
  "added": 1187,
  "modified": 42,
  "deleted": ["etc/motd"],
  "payloadBytes": 3073449,
  "processes": true
}

Because it is a plain tar, you can inspect an archive with standard tools:

tar tvf archive.tar | head
tar xf archive.tar .blaxel-archive/manifest.json -O | jq

An archive holds no memory, no /tmp, no runtime directory (/proc, /sys, /dev, /run, /mnt), no host-injected identity (/etc/resolv.conf, /etc/hostname, /etc/hosts, mounted secrets), nothing from the sandbox runtime’s own directories, which the manifest lists alongside the excludes above, and nothing from an attached volume or agent drive, which are separate filesystems with their own lifecycle. It also holds nothing from the image itself, so it is only meaningful on a sandbox created from that same image.

Export to a presigned URL

Presign a PUT on your bucket, then hand the URL to the sandbox. Set async so the call returns immediately: an archive of a large filesystem takes longer than a request can be held open.

curl -X POST "$SANDBOX_URL/archive/export" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $BL_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-bucket.s3.amazonaws.com/backups/my-sandbox.tar?X-Amz-Signature=...",
    "async": true
  }'

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

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

await fetch(`${sandbox.metadata.url}/archive/export`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BL_API_KEY}`,
    "X-Blaxel-Workspace": process.env.BL_WORKSPACE,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: presignedPutUrl, async: true }),
});

These options drive the export:

Option	Effect
`url`	Presigned `PUT` URL the archive is streamed to
`async`	Start the export and answer `202` right away, then follow it on `/archive/status`
`dryRun`	Report what would be archived, and its exact size, without stopping anything and without uploading
`saveProcesses`	Store the process list in the archive, `true` by default
`excludes`	Paths left out of the archive, added to the ones excluded by default
`headers`	Headers sent with the upload, for example `x-amz-storage-class`
`multipart`	Presigned multipart upload, for an archive above 5 GB

Size an archive before presigning

A dry run reads the filesystem and reports the exact byte count the upload will have, along with every path it would carry. Nothing is stopped and nothing is uploaded, so you can run it on a live sandbox.

curl -X POST "$SANDBOX_URL/archive/export" \
  -H "Authorization: Bearer $BL_API_KEY" \
  -H "X-Blaxel-Workspace: $BL_WORKSPACE" \
  -H "Content-Type: application/json" \
  -d '{ "dryRun": true }'

The size matters because the archive is streamed, not staged: S3 is told the length before the first byte is sent. Use the dry run to decide how many multipart parts to presign, or to skip an archive that grew beyond what you want to store.

Archives larger than 5 GB

A single presigned PUT accepts 5 GB. Above that, create a multipart upload on your storage, presign one PUT per part along with the completion and abort requests, and pass them to the export. The sandbox uses them in order and completes the upload itself.

{
  "multipart": {
    "partUrls": ["https://...part=1", "https://...part=2"],
    "partSize": 536870912,
    "completeUrl": "https://...uploadId=...",
    "abortUrl": "https://...uploadId=..."
  },
  "async": true
}

Parts must be at least 5 MB, and you have to presign enough of them for the archive: the export fails, without uploading, when the size it measured needs more parts than it was given. Extra parts are left unused. Always presign abortUrl so a failed export discards the parts it already sent instead of leaving them on your bucket.

Back up to cold storage

Anything you signed can be sent with the upload through headers, which is how an archive lands directly in an archival storage class:

{
  "url": "https://my-bucket.s3.amazonaws.com/backups/my-sandbox.tar?X-Amz-Signature=...",
  "headers": { "x-amz-storage-class": "GLACIER_IR" },
  "async": true
}

A presigned URL only accepts the headers it was signed for. Sign exactly the headers you send, or the storage rejects the upload as a signature mismatch.

For a backup that is never restarted, add "saveProcesses": false. The archive then holds the filesystem alone.

Follow an export

GET /archive/status reports the freeze and the background export:

{
  "state": "quiesced",
  "reason": "archive export",
  "readOnlyRoot": true,
  "stoppedProcesses": ["my-server"],
  "export": {
    "state": "running",
    "startedAt": "2026-08-27T09:12:44Z",
    "size": 3074211,
    "uploaded": false
  }
}

The export is running, then succeeded once the storage holds the archive, or failed with the reason. A failed export lifts the freeze itself, so the sandbox stays usable. After a successful one, the sandbox is frozen on purpose: delete it, or call POST /archive/resume to serve every route again. Resume does not start the stopped processes again.

Restore an archive into a sandbox

A sandbox restores an archive at boot, before its workload starts. Presign a GET on the archive and set it as BL_ARCHIVE_IMPORT_URL when you create the sandbox, from the same image the archive was taken from.

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

const sandbox = await SandboxInstance.createIfNotExists({
  name: "my-restored-sandbox",
  image: "blaxel/base-image:latest",
  envs: [{ name: "BL_ARCHIVE_IMPORT_URL", value: presignedGetUrl }],
});

from blaxel.core import SandboxInstance

sandbox = await SandboxInstance.create_if_not_exists({
    "name": "my-restored-sandbox",
    "image": "blaxel/base-image:latest",
    "envs": [{"name": "BL_ARCHIVE_IMPORT_URL", "value": presigned_get_url}],
})

The sandbox answers while the restore runs, and refuses the calls that write to the filesystem until it is done. Poll GET /archive/status to follow it: restore.state goes through downloading, extracting and relaunching, then succeeded, and restore.downloaded against restore.size gives you the progress. The processes the archive recorded are started again from their command line, with new IDs. Nothing is adopted from the archived sandbox, since its memory and its PIDs are gone. The archive is applied once. It is recorded on the restored filesystem, so the sandbox API restarting does not undo what the workload has done since, and a sandbox that boots again from the pristine image restores it anew.

A restore that fails after it has written to the filesystem leaves a mix of the image’s files and the archive’s. The sandbox quarantines itself instead of starting the workload on that mix: the root is remounted read-only and the failure is reported on /archive/status. Recreate the sandbox rather than trying to repair it.

What to keep in mind

A presigned URL is a credential. It is never logged by the sandbox and never appears in an error, and it should have the shortest lifetime that fits your transfer.
A transfer is bounded to one hour, so presign for at least as long as uploading or downloading your archive takes.
Restore into a sandbox created from the image the archive was taken from. An archive holds only the difference with that image.
Archives declare a format version. A sandbox refuses an archive newer than the format it understands, and reads gzip-compressed archives as well as plain ones.
One export runs at a time per sandbox, dry runs included. A second one is answered 409.

Sandbox overview

Learn more about sandbox lifecycle and configuration.

Snapshots and forking

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

Get Started

Sandboxes

Agent Drive

Volumes

Batch Jobs

Applications

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

Troubleshooting

Archive and unarchive sandboxes

Archive a sandbox

Unarchive a sandbox

Control the wait

Statuses

Archive to your own storage

Archive contents

Export to a presigned URL

Size an archive before presigning

Archives larger than 5 GB

Back up to cold storage

Follow an export

Restore an archive into a sandbox

What to keep in mind

Sandbox overview

Snapshots and forking

​Archive a sandbox

​Unarchive a sandbox

​Control the wait

​Statuses

​Archive to your own storage

​Archive contents

​Export to a presigned URL

​Size an archive before presigning

​Archives larger than 5 GB

​Back up to cold storage

​Follow an export

​Restore an archive into a sandbox

​What to keep in mind

Sandbox overview

Snapshots and forking

Archive a sandbox

Unarchive a sandbox

Control the wait

Statuses

Archive to your own storage

Archive contents

Export to a presigned URL

Size an archive before presigning

Archives larger than 5 GB

Back up to cold storage

Follow an export

Restore an archive into a sandbox

What to keep in mind