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

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

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:

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",
    },
)

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.

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

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

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

List snapshots

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')})")

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

Delete a snapshot

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

Snapshot on terminate

client.vms.update(
    vm_id="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