Sign in

v33

latestOpenAPI 3.1.0raw.githubusercontent.com2026-04-175267122.5 KB

Fork a new instance from a snapshot

post/snapshots/{snapshotId}/fork

Path parameters

snapshotIdstring required

Snapshot ID

Request body

namestring required

Name for the new instance (lowercase letters, digits, and dashes only; cannot start or end with a dash)

target_state'Stopped' | 'Standby' | 'Running'

Target state when restoring or forking from a snapshot

target_hypervisor'cloud-hypervisor' | 'firecracker' | 'qemu' | 'vz'

Optional hypervisor override. Allowed only when forking from a Stopped snapshot. Standby snapshots must fork with their original hypervisor.

Example request

{
  "name": "nginx-from-snap",
  "target_state": "Running",
  "target_hypervisor": "cloud-hypervisor"
}

Response

Forked instance created from snapshot

idstring required

Auto-generated unique identifier (CUID2 format)

namestring required

Human-readable name

imagestring required

OCI image reference

state'Created' | 'Initializing' | 'Running' | 'Paused' | 'Shutdown' | 'Stopped' | 'Standby' | 'Unknown' required

Instance state:

  • Created: VMM created but not started (Cloud Hypervisor native)
  • Initializing: VM is running while guest init is still in progress
  • Running: Guest program has started and instance is ready
  • Paused: VM is paused (Cloud Hypervisor native)
  • Shutdown: VM shut down but VMM exists (Cloud Hypervisor native)
  • Stopped: No VMM running, no snapshot exists
  • Standby: No VMM running, snapshot exists (can be restored)
  • Unknown: Failed to determine state (see state_error for details)
state_errorstring nullable

Error message if state couldn't be determined (only set when state is Unknown)

sizestring

Base memory size (human-readable)

hotplug_sizestring

Hotplug memory size (human-readable)

overlay_sizestring

Writable overlay disk size (human-readable)

vcpusinteger

Number of virtual CPUs

disk_io_bpsstring

Disk I/O rate limit (human-readable, e.g., "100MB/s")

envobject

Environment variables

tagsTags

User-defined key-value tags.

created_atstring date-time required

Creation timestamp (RFC3339)

started_atstring date-time nullable

Start timestamp (RFC3339)

stopped_atstring date-time nullable

Stop timestamp (RFC3339)

exit_codeinteger nullable

App exit code (null if VM hasn't exited)

exit_messagestring

Human-readable description of exit (e.g., "command not found", "killed by signal 9 (SIGKILL) - OOM")

has_snapshotboolean

Whether a snapshot exists for this instance

hypervisor'cloud-hypervisor' | 'firecracker' | 'qemu' | 'vz'

Hypervisor running this instance

Example response

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "name": "my-workload-1",
  "image": "docker.io/library/alpine:latest",
  "state_error": "failed to query VMM: connection refused",
  "size": "2GB",
  "hotplug_size": "2GB",
  "overlay_size": "10GB",
  "vcpus": 2,
  "disk_io_bps": "100MB/s",
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "network": {
    "enabled": true,
    "name": "default",
    "ip": "192.168.100.10",
    "mac": "02:00:00:ab:cd:ef",
    "bandwidth_download": "125MB/s",
    "bandwidth_upload": "125MB/s"
  },
  "volumes": [
    {
      "volume_id": "vol-abc123",
      "mount_path": "/mnt/data",
      "overlay_size": "1GB"
    }
  ],
  "gpu": {
    "profile": "L40S-1Q",
    "mdev_uuid": "aa618089-8b16-4d01-a136-25a0f3c73123"
  },
  "created_at": "2025-01-15T10:30:00Z",
  "started_at": "2025-01-15T10:30:05Z",
  "stopped_at": "2025-01-15T12:30:00Z",
  "exit_code": 137,
  "exit_message": "killed by signal 9 (SIGKILL)",
  "hypervisor": "cloud-hypervisor",
  "snapshot_policy": {
    "compression": {
      "enabled": true,
      "algorithm": "zstd",
      "level": 1
    },
    "standby_compression_delay": "2m"
  },
  "auto_standby": {
    "enabled": true,
    "idle_timeout": "5m",
    "ignore_source_cidrs": [
      "10.0.0.0/8",
      "192.168.0.0/16"
    ],
    "ignore_destination_ports": [
      22,
      9000
    ]
  }
}