Skip to content
hypeman
Get started
API Reference

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
Get filesystem path info
get/instances/{id}/stat
ModelsExpand Collapse
Instance = object { id, created_at, image, 16 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"
disk_io_bps: optional string

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

env: optional map[string]

Environment variables

gpu: optional object { mdev_uuid, profile }

GPU information attached to the instance

mdev_uuid: optional string

mdev device UUID

profile: optional string

vGPU profile name

has_snapshot: optional boolean

Whether a snapshot exists for this instance

hotplug_size: optional string

Hotplug memory size (human-readable)

hypervisor: optional "cloud-hypervisor" or "qemu"

Hypervisor running this instance

Accepts one of the following:
"cloud-hypervisor"
"qemu"
network: optional object { bandwidth_download, bandwidth_upload, enabled, 3 more }

Network configuration of the instance

bandwidth_download: optional string

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

bandwidth_upload: optional string

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

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

PathInfo = object { exists, error, is_dir, 5 more }
exists: boolean

Whether the path exists

error: optional string

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: optional boolean

True if this is a directory

is_file: optional boolean

True if this is a regular file

mode: optional number

File mode (Unix permissions)

size: optional number

File size in bytes

formatint64
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}