Snapshots & Archives

Memory snapshots save RAM and virtual-device state for resuming the same workspace. The workspace retains its existing writable disk; a memory snapshot is not a versioned disk backup. Archives are disk-only backups that can be versioned.

In the dashboard, Hibernate calls snapshot with after: "stop", releases the VM process and RAM, and shows Hibernated. Resume then calls restore. Pause is separate: it only freezes execution and keeps RAM allocated.

Nested KVM workspaces, including the current Mac image, reject memory snapshot and restore with HTTP 409. Their Pause/Resume still preserves the live session in RAM. workspace.lifecycle.snapshot_supported and snapshot_unavailable_reason expose this capability.

Create snapshot

Take a snapshot of the current workspace state.

await ws.snapshots.create('ws_a1b2c3d4', {
  after: 'stop', // Hibernate: preserve RAM and the unchanged writable disk
});

POST /workspace/:workspaceId/snapshot

{
  "after": "stop"
}

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/snapshot" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "after": "stop" }'

Parameters

The after parameter controls the VM state post-snapshot:

• "pause" - the VM remains frozen with RAM allocated ("paused" is accepted as a compatibility alias)
• "stop" - the VM becomes suspended: RAM is released and restore is required to resume

after: "resume" is rejected for workspaces with writable disks. Resuming writes would make the saved memory disagree with the disk. Resuming a paused checkpoint consumes its saved execution files; it does not leave a rollback point.

Restore snapshot

Restore saved RAM and virtual-device state on the workspace's current host, using its retained writable disk. This continues the saved session and processes. Restore applies credit and running-resource checks and refreshes access routes. A missing or failed snapshot returns an error; it does not silently cold boot.

Restore requires a suspended workspace with no live VM process. A cold stop or restart cannot subsequently restore older memory over a disk that may have changed. Use a disk archive when you need a versioned filesystem backup. Disk mutation and resizing are blocked while saved execution is retained.

await ws.snapshots.restore('ws_a1b2c3d4');

POST /workspace/:workspaceId/restore

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/restore" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Create archive

Create a versioned disk archive. Archives are lighter than snapshots - they capture the disk but not memory state.

Stop the workspace completely before creating an archive. Archive creation holds the workspace lifecycle lock until the copy is complete, so start and resize cannot race the backup. For application-consistent database backups, pause writes or take a database-native backup before stopping. Live Pages exports use the guest filesystem and are not database snapshots.

await ws.snapshots.createArchive('ws_a1b2c3d4', {
  version: 1,
  format: 'targz',
  vm_paths: ['/app', '/data'],
  exclude_vm_paths: ['/app/node_modules'],
});

POST /workspace/:workspaceId/archives

{
  "version": 1,
  "format": "targz",
  "vm_paths": ["/app", "/data"],
  "exclude_vm_paths": ["/app/node_modules"]
}

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/archives" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "vm_paths": ["/app"],
    "exclude_vm_paths": ["/app/node_modules"]
  }'

Parameters

List archives

Get all archives for a workspace.

const archives = await ws.snapshots.listArchives('ws_a1b2c3d4');

GET /workspace/:workspaceId/archives

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/archives" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response

{
  "success": true,
  "archives": [
    { "version": 1, "created_at": "2026-02-24T10:30:00Z", "size": 52428800 },
    { "version": 2, "created_at": "2026-02-24T12:00:00Z", "size": 53477376 }
  ]
}

Get archive

Get details of a specific archive version.

const archive = await ws.snapshots.getArchive('ws_a1b2c3d4', '1');

GET /workspace/:workspaceId/archives/:version

curl "https://api.oblien.com/workspace/ws_a1b2c3d4/archives/1" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Delete archive

Delete a specific archive version.

await ws.snapshots.deleteArchive('ws_a1b2c3d4', '1', {
  delete_file: true,
});

DELETE /workspace/:workspaceId/archives/:version?delete_file=true

curl -X DELETE "https://api.oblien.com/workspace/ws_a1b2c3d4/archives/1?delete_file=true" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Query parameters

Delete all archives

Delete all archives for a workspace.

await ws.snapshots.deleteAllArchives('ws_a1b2c3d4', {
  delete_files: true,
});

DELETE /workspace/:workspaceId/archives?delete_files=true

curl -X DELETE "https://api.oblien.com/workspace/ws_a1b2c3d4/archives?delete_files=true" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Query parameters