Instances

List instances

client.instances.list(?, ?): InstanceListResponse { id, created_at, image, 19 more }

get/instances

Create and start instance

client.instances.create(, ?): Instance { id, created_at, image, 19 more }

post/instances

Get instance details

client.instances.get(, ?): Instance { id, created_at, image, 19 more }

get/instances/{id}

Update instance properties

client.instances.update(, , ?): Instance { id, created_at, image, 19 more }

patch/instances/{id}

Stop and delete instance

client.instances.delete(, ?): void

delete/instances/{id}

Put instance in standby (pause, snapshot, delete VMM)

client.instances.standby(, ?): Instance { id, created_at, image, 19 more }

post/instances/{id}/standby

Restore instance from standby

client.instances.restore(, ?): Instance { id, created_at, image, 19 more }

post/instances/{id}/restore

Fork an instance from stopped, standby, or running (with from_running=true)

client.instances.fork(, , ?): Instance { id, created_at, image, 19 more }

post/instances/{id}/fork

Start a stopped instance

client.instances.start(, , ?): Instance { id, created_at, image, 19 more }

post/instances/{id}/start

Stop instance (graceful shutdown)

client.instances.stop(, ?): Instance { id, created_at, image, 19 more }

post/instances/{id}/stop

Stream instance logs (SSE)

client.instances.logs(, ?, ?): InstanceLogsResponse | Stream<InstanceLogsResponse>

get/instances/{id}/logs

Get filesystem path info

client.instances.stat(, , ?): PathInfo { exists, error, is_dir, 5 more }

get/instances/{id}/stat

Get instance resource utilization stats

client.instances.stats(, ?): InstanceStats { allocated_memory_bytes, allocated_vcpus, cpu_seconds, 7 more }

get/instances/{id}/stats

ModelsExpand Collapse

Instance { id, created_at, image, 19 more }

id: string

Auto-generated unique identifier (CUID2 format)

created_at: string

Creation timestamp (RFC3339)

formatdate-time

image: string

OCI image reference

name: string

Human-readable name

state: "Created" | "Initializing" | "Running" | 5 more

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)

Accepts one of the following:

"Created"

"Initializing"

"Running"

"Paused"

"Shutdown"

"Stopped"

"Standby"

"Unknown"

disk_io_bps?: string

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

env?: Record<string, string>

Environment variables

exit_code?: number | null

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

exit_message?: string

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

gpu?: GPU { mdev_uuid, profile }

GPU information attached to the instance

mdev_uuid?: string

mdev device UUID

profile?: string

vGPU profile name

has_snapshot?: boolean

Whether a snapshot exists for this instance

hotplug_size?: string

Hotplug memory size (human-readable)

hypervisor?: "cloud-hypervisor" | "firecracker" | "qemu" | "vz"

Hypervisor running this instance

Accepts one of the following:

"cloud-hypervisor"

"firecracker"

"qemu"

"vz"

network?: Network { bandwidth_download, bandwidth_upload, enabled, 3 more }

Network configuration of the instance

bandwidth_download?: string

Download bandwidth limit (human-readable, e.g., "1Gbps", "125MB/s")

bandwidth_upload?: string

Upload bandwidth limit (human-readable, e.g., "1Gbps", "125MB/s")

enabled?: boolean

Whether instance is attached to the default network

ip?: string | null

Assigned IP address (null if no network)

mac?: string | null

Assigned MAC address (null if no network)

name?: string

Network name (always "default" when enabled)

overlay_size?: string

Writable overlay disk size (human-readable)

size?: string

Base memory size (human-readable)

started_at?: string | null

Start timestamp (RFC3339)

formatdate-time

state_error?: string | null

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

stopped_at?: string | null

Stop timestamp (RFC3339)

formatdate-time

tags?: Record<string, string>

User-defined key-value tags.

vcpus?: number

Number of virtual CPUs

volumes?: Array<VolumeMount { mount_path, volume_id, overlay, 2 more } >

Volumes attached to the instance

mount_path: string

Path where volume is mounted in the guest

volume_id: string

Volume identifier

overlay?: boolean

Create per-instance overlay for writes (requires readonly=true)

overlay_size?: string

Max overlay size as human-readable string (e.g., "1GB"). Required if overlay=true.

readonly?: boolean

Whether volume is mounted read-only

InstanceStats { allocated_memory_bytes, allocated_vcpus, cpu_seconds, 7 more }

Real-time resource utilization statistics for a VM instance

allocated_memory_bytes: number

Total memory allocated to the VM (Size + HotplugSize) in bytes

formatint64

allocated_vcpus: number

Number of vCPUs allocated to the VM

cpu_seconds: number

Total CPU time consumed by the VM hypervisor process in seconds

formatdouble

instance_id: string

Instance identifier

instance_name: string

Instance name

memory_rss_bytes: number

Resident Set Size - actual physical memory used by the VM in bytes

formatint64

memory_vms_bytes: number

Virtual Memory Size - total virtual memory allocated in bytes

formatint64

network_rx_bytes: number

Total network bytes received by the VM (from TAP interface)

formatint64

network_tx_bytes: number

Total network bytes transmitted by the VM (from TAP interface)

formatint64

memory_utilization_ratio?: number | null

Memory utilization ratio (RSS / allocated memory). Only present when allocated_memory_bytes > 0.

formatdouble

PathInfo { exists, error, is_dir, 5 more }

exists: boolean

Whether the path exists

error?: string | null

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.

is_dir?: boolean

True if this is a directory

is_file?: boolean

True if this is a regular file

is_symlink?: boolean

True if this is a symbolic link (only set when follow_links=false)

link_target?: string | null

Symlink target path (only set when is_symlink=true)

mode?: number

File mode (Unix permissions)

size?: number

File size in bytes

formatint64

PortMapping { guest_port, host_port, protocol }

guest_port: number

Port in the guest VM

host_port: number

Port on the host

protocol?: "tcp" | "udp"

Accepts one of the following:

"tcp"

"udp"

VolumeMount { mount_path, volume_id, overlay, 2 more }

mount_path: string

Path where volume is mounted in the guest

volume_id: string

Volume identifier

overlay?: boolean

Create per-instance overlay for writes (requires readonly=true)

overlay_size?: string

Max overlay size as human-readable string (e.g., "1GB"). Required if overlay=true.

readonly?: boolean

Whether volume is mounted read-only

InstancesVolumes

Attach volume to instance

client.instances.volumes.attach(, , ?): Instance { id, created_at, image, 19 more }

post/instances/{id}/volumes/{volumeId}

Detach volume from instance

client.instances.volumes.detach(, , ?): Instance { id, created_at, image, 19 more }

delete/instances/{id}/volumes/{volumeId}

InstancesSnapshots

Create a snapshot for an instance

client.instances.snapshots.create(, , ?): Snapshot { id, created_at, kind, 6 more }

post/instances/{id}/snapshots

Restore an instance from a snapshot in-place

client.instances.snapshots.restore(, , ?): Instance { id, created_at, image, 19 more }

post/instances/{id}/snapshots/{snapshotId}/restore