Instances
List instances
Create and start instance
Get instance details
Update instance properties
Stop and delete instance
Put instance in standby (pause, snapshot, delete VMM)
Restore instance from standby
Fork an instance from stopped, standby, or running (with from_running=true)
Start a stopped instance
Stop instance (graceful shutdown)
Stream instance logs (SSE)
Get filesystem path info
Get instance resource utilization stats
Wait for instance to reach a target state
ModelsExpand Collapse
Instance = object { id, created_at, image, 20 more }
Auto-generated unique identifier (CUID2 format)
Creation timestamp (RFC3339)
OCI image reference
Human-readable name
state: "Created" or "Initializing" or "Running" or 5 moreInstance 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)
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)
Disk I/O rate limit (human-readable, e.g., "100MB/s")
Environment variables
App exit code (null if VM hasn't exited)
Human-readable description of exit (e.g., "command not found", "killed by signal 9 (SIGKILL) - OOM")
gpu: optional object { mdev_uuid, profile } GPU information attached to the instance
GPU information attached to the instance
mdev device UUID
vGPU profile name
Whether a snapshot exists for this instance
Hotplug memory size (human-readable)
hypervisor: optional "cloud-hypervisor" or "firecracker" or "qemu" or "vz"Hypervisor running this instance
Hypervisor running this instance
network: optional object { bandwidth_download, bandwidth_upload, enabled, 3 more } Network configuration of the instance
Network configuration of the instance
Download bandwidth limit (human-readable, e.g., "1Gbps", "125MB/s")
Upload bandwidth limit (human-readable, e.g., "1Gbps", "125MB/s")
Whether instance is attached to the default network
Assigned IP address (null if no network)
Assigned MAC address (null if no network)
Network name (always "default" when enabled)
Writable overlay disk size (human-readable)
Base memory size (human-readable)
Enable snapshot memory compression
algorithm: optional "zstd" or "lz4"Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.
Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.
Compression level. Allowed ranges are zstd=1-19 and lz4=0-9. When omitted, zstd defaults to 1 and lz4 defaults to 0. Ignored when enabled is false.
Start timestamp (RFC3339)
Error message if state couldn't be determined (only set when state is Unknown)
Stop timestamp (RFC3339)
User-defined key-value tags.
Number of virtual CPUs
Volumes attached to the instance
Volumes attached to the instance
Path where volume is mounted in the guest
Volume identifier
Create per-instance overlay for writes (requires readonly=true)
Max overlay size as human-readable string (e.g., "1GB"). Required if overlay=true.
Whether volume is mounted read-only
InstanceStats = object { allocated_memory_bytes, allocated_vcpus, cpu_seconds, 7 more } Real-time resource utilization statistics for a VM instance
Real-time resource utilization statistics for a VM instance
Total memory allocated to the VM (Size + HotplugSize) in bytes
Number of vCPUs allocated to the VM
Total CPU time consumed by the VM hypervisor process in seconds
Instance identifier
Instance name
Resident Set Size - actual physical memory used by the VM in bytes
Virtual Memory Size - total virtual memory allocated in bytes
Total network bytes received by the VM (from TAP interface)
Total network bytes transmitted by the VM (from TAP interface)
Memory utilization ratio (RSS / allocated memory). Only present when allocated_memory_bytes > 0.
PathInfo = object { exists, error, is_dir, 5 more }
Whether the path exists
Error message if stat failed (e.g., permission denied). Only set when exists is false due to an error rather than the path not existing.
True if this is a directory
True if this is a regular file
True if this is a symbolic link (only set when follow_links=false)
Symlink target path (only set when is_symlink=true)
File mode (Unix permissions)
File size in bytes
PortMapping = object { guest_port, host_port, protocol }
Port in the guest VM
Port on the host
protocol: optional "tcp" or "udp"
SetSnapshotScheduleRequest = object { interval, retention, metadata, name_prefix }
Snapshot interval (Go duration format, minimum 1m).
At least one of max_count or max_age must be provided.
At least one of max_count or max_age must be provided.
Delete scheduled snapshots older than this duration (Go duration format).
Keep at most this many scheduled snapshots for the instance (0 disables count-based cleanup).
User-defined key-value tags.
Optional prefix for auto-generated scheduled snapshot names (max 47 chars).
SnapshotPolicy = object { compression }
Enable snapshot memory compression
algorithm: optional "zstd" or "lz4"Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.
Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.
Compression level. Allowed ranges are zstd=1-19 and lz4=0-9. When omitted, zstd defaults to 1 and lz4 defaults to 0. Ignored when enabled is false.
SnapshotSchedule = object { created_at, instance_id, interval, 8 more }
Schedule creation timestamp.
Source instance ID.
Snapshot interval (Go duration format).
Next scheduled run time.
Automatic cleanup policy for scheduled snapshots.
Automatic cleanup policy for scheduled snapshots.
Delete scheduled snapshots older than this duration (Go duration format).
Keep at most this many scheduled snapshots for the instance (0 disables count-based cleanup).
Schedule update timestamp.
Last schedule run error, if any.
Last schedule execution time.
Snapshot ID produced by the last successful run.
User-defined key-value tags.
Optional prefix used for generated scheduled snapshot names.
SnapshotScheduleRetention = object { max_age, max_count } Automatic cleanup policy for scheduled snapshots.
Automatic cleanup policy for scheduled snapshots.
Delete scheduled snapshots older than this duration (Go duration format).
Keep at most this many scheduled snapshots for the instance (0 disables count-based cleanup).
VolumeMount = object { mount_path, volume_id, overlay, 2 more }
Path where volume is mounted in the guest
Volume identifier
Create per-instance overlay for writes (requires readonly=true)
Max overlay size as human-readable string (e.g., "1GB"). Required if overlay=true.
Whether volume is mounted read-only
WaitForStateResponse = object { state, timed_out, state_error }
state: "Created" or "Initializing" or "Running" or 5 moreCurrent instance state when the wait completed
Current instance state when the wait completed
Whether the timeout expired before the target state was reached
Error message when derived state is Unknown