Snapshots

Snapshots capture VM disk state plus snapshot metadata so new VMs can boot from a prebuilt environment in milliseconds.

Why use snapshots

• Fast cold starts -- boot with dependencies already installed.
• Reproducibility -- launch the same environment repeatedly.
• Custom base images -- build from any OCI/Docker image, then reuse.

Snapshot creation modes

You can create snapshots in two ways:

1. From a running VM with POST /v1/vms/{vm_id}/snapshot.
2. From an OCI image with POST /v1/snapshots (async build).

Use VM snapshots when you already configured a live VM. Use OCI snapshots when you want an image-to-snapshot build pipeline.

Create from a running VM

CLI

# Create a VM, configure it, then snapshot
instavm create
# ... install packages, configure files via SSH ...
instavm snapshot create <vm_id> --name python-ml-environment

Python

from instavm import InstaVM

client = InstaVM("your_api_key")

vm = client.vms.create(wait=True)
# ... install packages / configure files ...

snapshot = client.vms.snapshot(
    vm_id=vm["vm_id"],
    wait=True,
    name="python-ml-environment",
)

snapshot_id = snapshot.get("snapshot_id") or snapshot.get("id")
print(f"Snapshot ID: {snapshot_id}")

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');

const vm = await client.vms.create({}, true);
// ... install packages / configure files ...

const snapshot = await client.vms.snapshot(vm.vm_id, {
  name: 'python-ml-environment',
}, true);

console.log(`Snapshot ID: ${snapshot.snapshot_id || snapshot.id}`);

Create from an OCI image

POST /v1/snapshots requires oci_image. Other fields are optional.

Field	Required	Default / Limits	Notes
oci_image	Yes	string	OCI image reference, for example docker.io/library/python:3.11-slim.
name	No	null	Snapshot display name.
vcpu_count	No	2 (min 1, max 8)	vCPU count for build VM.
memory_mb	No	512 (min 128, max 8192)	Memory for build VM.
type	No	user	Must match user or system.
build_args	No	null	Build-time customization object (see below).

Supported build_args fields:

Field	Type	Notes
extra_apt_packages	string	Space-separated apt package names.
extra_pip_packages	string	Space-separated pip package names.
extra_npm_packages	string	Space-separated npm package names.
git_clone_url	string	Cloned into /app/repo.
git_clone_branch	string	Defaults to repository default branch.
disk_size_gb	integer	1-3; default worker behavior is 3 and values above 3 are capped.
envs	object	Environment variables as string key-value pairs.
post_build_cmd	string	Shell command run after package installation.

Example:

CLI

instavm snapshot build docker.io/library/python:3.11-slim \
  --name python-3.11-data-stack \
  --vcpu 2 \
  --memory 1024 \
  --apt "git ffmpeg" \
  --pip "numpy pandas scikit-learn" \
  --git-clone https://github.com/example/repo.git \
  --git-branch main \
  --disk-size 3 \
  --env APP_ENV=prod \
  --env PYTHONUNBUFFERED=1 \
  --run "pip install -r /app/repo/requirements.txt"

Python

snapshot = client.snapshots.create(
    oci_image="docker.io/library/python:3.11-slim",
    name="python-3.11-data-stack",
    vcpu_count=2,
    memory_mb=1024,
    type="user",
    build_args={
        "extra_apt_packages": "git ffmpeg",
        "extra_pip_packages": "numpy pandas scikit-learn",
        "git_clone_url": "https://github.com/example/repo.git",
        "git_clone_branch": "main",
        "disk_size_gb": 3,
        "envs": {"APP_ENV": "prod", "PYTHONUNBUFFERED": "1"},
        "post_build_cmd": "pip install -r /app/repo/requirements.txt",
    },
)

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');

const snapshot = await client.snapshots.create({
  oci_image: 'docker.io/library/python:3.11-slim',
  name: 'python-3.11-data-stack',
  vcpu_count: 2,
  memory_mb: 1024,
  type: 'user',
  build_args: {
    extra_apt_packages: 'git ffmpeg',
    extra_pip_packages: 'numpy pandas scikit-learn',
    git_clone_url: 'https://github.com/example/repo.git',
    git_clone_branch: 'main',
    disk_size_gb: 3,
    envs: { APP_ENV: 'prod', PYTHONUNBUFFERED: '1' },
    post_build_cmd: 'pip install -r /app/repo/requirements.txt',
  },
});

Async build behavior

OCI-image snapshot creation is asynchronous. The create call returns a snapshot record immediately. Check status and last_error with client.snapshots.get(...) or client.snapshots.list(...) until build completion.

CLI

# Poll build status
instavm snapshot get <snapshot_id> --json

# Watch until status is "ready" or "failed"
watch -n 5 instavm snapshot get <snapshot_id> --json

Python

snapshot_id = snapshot.get("snapshot_id") or snapshot.get("id")
terminal_statuses = {"ready", "failed"}  # adjust to statuses used by your deployment

while True:
    current = client.snapshots.get(snapshot_id=snapshot_id)
    status = current.get("status")
    print("status:", status)
    if status in terminal_statuses:
        if status == "failed":
            print("error:", current.get("last_error"))
        break

JavaScript

const snapshotId = snapshot.snapshot_id || snapshot.id;
const terminalStatuses = new Set(['ready', 'failed']);

while (true) {
  const current = await client.snapshots.get(snapshotId);
  console.log('status:', current.status);
  if (terminalStatuses.has(current.status)) {
    if (current.status === 'failed') {
      console.log('error:', current.last_error);
    }
    break;
  }
  await new Promise(r => setTimeout(r, 5000));
}

Snapshot fields you can rely on

Snapshot records include:

• id
• name
• status
• snapshot_type
• type
• source_vm_id
• oci_image
• vcpu_count
• memory_mb
• size_bytes
• is_public
• last_error
• created_at
• updated_at

Boot a VM from a snapshot

CLI

instavm create --snapshot snap_xyz789

Python

vm = client.vms.create(
    snapshot_id="snap_xyz789",
    wait=True,
)

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');

const vm = await client.vms.create({
  snapshot_id: 'snap_xyz789',
}, true);

List snapshots

CLI

instavm snapshot ls

# Filter by type
instavm snapshot ls --type user

Python

snapshots = client.snapshots.list()
for snap in snapshots:
    snap_id = snap.get("snapshot_id") or snap.get("id")
    print(f"{snap.get('name', 'unnamed')}: {snap_id} ({snap.get('type', 'user')})")

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');

const snapshots = await client.snapshots.list();
for (const snap of snapshots) {
  const snapId = snap.snapshot_id || snap.id;
  console.log(`${snap.name || 'unnamed'}: ${snapId} (${snap.type || 'user'})`);
}

The REST API also supports filtering by type (GET /v1/snapshots?type=user or type=system).

Delete a snapshot

CLI

instavm snapshot rm snap_xyz789

Python

client.snapshots.delete(snapshot_id="snap_xyz789")

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');
await client.snapshots.delete('snap_xyz789');

Snapshot on terminate

Python

client.vms.update(
    vm_id="vm_abc123",
    snapshot_on_terminate=True,
    snapshot_name="final-state",
)

CLI

# No direct CLI command — use the SDK or REST API
curl -X PATCH https://api.instavm.io/v1/vms/vm_abc123 \
  -H "X-API-Key: $INSTAVM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_on_terminate": true, "snapshot_name": "final-state"}'

JavaScript

import { InstaVM } from 'instavm';

const client = new InstaVM('your_api_key');
await client.vms.update('vm_abc123', {
  snapshot_on_terminate: true,
  snapshot_name: 'final-state',
});

Next steps

• Sandboxes -- VM runtime model behind snapshots
• Python SDK: Snapshots -- SDK usage
• REST API: Snapshots -- endpoint details and schemas