Instances

List instances

get/instances

Create and start instance

post/instances

Get instance details

get/instances/{id}

Stop and delete instance

delete/instances/{id}

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

post/instances/{id}/standby

Restore instance from standby

post/instances/{id}/restore

Start a stopped instance

post/instances/{id}/start

Stop instance (graceful shutdown)

post/instances/{id}/stop

Stream instance logs (SSE)

get/instances/{id}/logs

ModelsExpand Collapse

Instance = object { id, created_at, image, 13 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" or "Running" or "Paused" or 4 more

Instance state:

Created: VMM created but not started (Cloud Hypervisor native)
Running: VM is actively running (Cloud Hypervisor native)
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"

"Running"

"Paused"

"Shutdown"

"Stopped"

"Standby"

"Unknown"

env: optional map[string]

Environment variables

has_snapshot: optional boolean

Whether a snapshot exists for this instance

hotplug_size: optional string

Hotplug memory size (human-readable)

network: optional object { enabled, ip, mac, name }

Network configuration of the instance

enabled: optional boolean

Whether instance is attached to the default network

ip: optional string

Assigned IP address (null if no network)

mac: optional string

Assigned MAC address (null if no network)

name: optional string

Network name (always "default" when enabled)

overlay_size: optional string

Writable overlay disk size (human-readable)

size: optional string

Base memory size (human-readable)

started_at: optional string

Start timestamp (RFC3339)

formatdate-time

state_error: optional string

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

stopped_at: optional string

Stop timestamp (RFC3339)

formatdate-time

vcpus: optional number

Number of virtual CPUs

volumes: optional array of 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: optional boolean

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

overlay_size: optional string

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

readonly: optional boolean

Whether volume is mounted read-only

PortMapping = object { guest_port, host_port, protocol }

guest_port: number

Port in the guest VM

host_port: number

Port on the host

protocol: optional "tcp" or "udp"

Accepts one of the following:

"tcp"

"udp"

VolumeMount = object { mount_path, volume_id, overlay, 2 more }

mount_path: string

Path where volume is mounted in the guest

volume_id: string

Volume identifier

overlay: optional boolean

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

overlay_size: optional string

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

readonly: optional boolean

Whether volume is mounted read-only

InstancesVolumes

Attach volume to instance

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

Detach volume from instance

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