Skip to content
hypeman
Get started
API Reference

Instances

List instances
client.instances.list(InstanceListParams { state, tags } query?, RequestOptionsoptions?): InstanceListResponse { id, created_at, image, 20 more }
get/instances
Create and start instance
client.instances.create(InstanceCreateParams { image, name, cmd, 17 more } body, RequestOptionsoptions?): Instance { id, created_at, image, 20 more }
post/instances
Get instance details
client.instances.get(stringid, RequestOptionsoptions?): Instance { id, created_at, image, 20 more }
get/instances/{id}
Update instance properties
client.instances.update(stringid, InstanceUpdateParams { env } body, RequestOptionsoptions?): Instance { id, created_at, image, 20 more }
patch/instances/{id}
Stop and delete instance
client.instances.delete(stringid, RequestOptionsoptions?): void
delete/instances/{id}
Put instance in standby (pause, snapshot, delete VMM)
client.instances.standby(stringid, InstanceStandbyParams { compression } body?, RequestOptionsoptions?): Instance { id, created_at, image, 20 more }
post/instances/{id}/standby
Restore instance from standby
client.instances.restore(stringid, RequestOptionsoptions?): Instance { id, created_at, image, 20 more }
post/instances/{id}/restore
Fork an instance from stopped, standby, or running (with from_running=true)
client.instances.fork(stringid, InstanceForkParams { name, from_running, target_state } body, RequestOptionsoptions?): Instance { id, created_at, image, 20 more }
post/instances/{id}/fork
Start a stopped instance
client.instances.start(stringid, InstanceStartParams { cmd, entrypoint } body, RequestOptionsoptions?): Instance { id, created_at, image, 20 more }
post/instances/{id}/start
Stop instance (graceful shutdown)
client.instances.stop(stringid, RequestOptionsoptions?): Instance { id, created_at, image, 20 more }
post/instances/{id}/stop
Stream instance logs (SSE)
client.instances.logs(stringid, InstanceLogsParams { follow, source, tail } query?, RequestOptionsoptions?): InstanceLogsResponse | Stream<InstanceLogsResponse>
get/instances/{id}/logs
Get filesystem path info
client.instances.stat(stringid, InstanceStatParams { path_, follow_links } query, RequestOptionsoptions?): PathInfo { exists, error, is_dir, 5 more }
get/instances/{id}/stat
Get instance resource utilization stats
client.instances.stats(stringid, RequestOptionsoptions?): InstanceStats { allocated_memory_bytes, allocated_vcpus, cpu_seconds, 7 more }
get/instances/{id}/stats
Wait for instance to reach a target state
client.instances.wait(stringid, InstanceWaitParams { state, timeout } query, RequestOptionsoptions?): WaitForStateResponse { state, timed_out, state_error }
get/instances/{id}/wait
ModelsExpand Collapse
Instance { id, created_at, image, 20 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)

snapshot_policy?: SnapshotPolicy { compression }
compression?: SnapshotCompressionConfig { enabled, algorithm, level }
enabled: boolean

Enable snapshot memory compression

algorithm?: "zstd" | "lz4"

Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.

Accepts one of the following:
"zstd"
"lz4"
level?: number

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.

minimum0
maximum19
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

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"
SetSnapshotScheduleRequest { interval, retention, metadata, name_prefix }
interval: string

Snapshot interval (Go duration format, minimum 1m).

retention: SnapshotScheduleRetention { max_age, max_count }

At least one of max_count or max_age must be provided.

max_age?: string

Delete scheduled snapshots older than this duration (Go duration format).

max_count?: number

Keep at most this many scheduled snapshots for the instance (0 disables count-based cleanup).

minimum0
metadata?: Record<string, string>

User-defined key-value tags.

name_prefix?: string | null

Optional prefix for auto-generated scheduled snapshot names (max 47 chars).

maxLength47
SnapshotPolicy { compression }
compression?: SnapshotCompressionConfig { enabled, algorithm, level }
enabled: boolean

Enable snapshot memory compression

algorithm?: "zstd" | "lz4"

Compression algorithm (defaults to zstd when enabled). Ignored when enabled is false.

Accepts one of the following:
"zstd"
"lz4"
level?: number

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.

minimum0
maximum19
SnapshotSchedule { created_at, instance_id, interval, 8 more }
created_at: string

Schedule creation timestamp.

formatdate-time
instance_id: string

Source instance ID.

interval: string

Snapshot interval (Go duration format).

next_run_at: string

Next scheduled run time.

formatdate-time
retention: SnapshotScheduleRetention { max_age, max_count }

Automatic cleanup policy for scheduled snapshots.

max_age?: string

Delete scheduled snapshots older than this duration (Go duration format).

max_count?: number

Keep at most this many scheduled snapshots for the instance (0 disables count-based cleanup).

minimum0
updated_at: string

Schedule update timestamp.

formatdate-time
last_error?: string | null

Last schedule run error, if any.

last_run_at?: string | null

Last schedule execution time.

formatdate-time
last_snapshot_id?: string | null

Snapshot ID produced by the last successful run.

metadata?: Record<string, string>

User-defined key-value tags.

name_prefix?: string | null

Optional prefix used for generated scheduled snapshot names.

SnapshotScheduleRetention { max_age, max_count }

Automatic cleanup policy for scheduled snapshots.

max_age?: string

Delete scheduled snapshots older than this duration (Go duration format).

max_count?: number

Keep at most this many scheduled snapshots for the instance (0 disables count-based cleanup).

minimum0
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

WaitForStateResponse { state, timed_out, state_error }
state: "Created" | "Initializing" | "Running" | 5 more

Current instance state when the wait completed

Accepts one of the following:
"Created"
"Initializing"
"Running"
"Paused"
"Shutdown"
"Stopped"
"Standby"
"Unknown"
timed_out: boolean

Whether the timeout expired before the target state was reached

state_error?: string | null

Error message when derived state is Unknown

InstancesVolumes

Attach volume to instance
client.instances.volumes.attach(stringvolumeID, VolumeAttachParams { id, mount_path, readonly } params, RequestOptionsoptions?): Instance { id, created_at, image, 20 more }
post/instances/{id}/volumes/{volumeId}
Detach volume from instance
client.instances.volumes.detach(stringvolumeID, VolumeDetachParams { id } params, RequestOptionsoptions?): Instance { id, created_at, image, 20 more }
delete/instances/{id}/volumes/{volumeId}

InstancesSnapshots

Create a snapshot for an instance
client.instances.snapshots.create(stringid, SnapshotCreateParams { kind, compression, name, tags } body, RequestOptionsoptions?): Snapshot { id, created_at, kind, 11 more }
post/instances/{id}/snapshots
Restore an instance from a snapshot in-place
client.instances.snapshots.restore(stringsnapshotID, SnapshotRestoreParams { id, target_hypervisor, target_state } params, RequestOptionsoptions?): Instance { id, created_at, image, 20 more }
post/instances/{id}/snapshots/{snapshotId}/restore

InstancesSnapshot Schedule

Get snapshot schedule for an instance
client.instances.snapshotSchedule.get(stringid, RequestOptionsoptions?): SnapshotSchedule { created_at, instance_id, interval, 8 more }
get/instances/{id}/snapshot-schedule
Create or update snapshot schedule for an instance
client.instances.snapshotSchedule.update(stringid, SnapshotScheduleUpdateParams { interval, retention, metadata, name_prefix } body, RequestOptionsoptions?): SnapshotSchedule { created_at, instance_id, interval, 8 more }
put/instances/{id}/snapshot-schedule
Delete snapshot schedule for an instance
client.instances.snapshotSchedule.delete(stringid, RequestOptionsoptions?): void
delete/instances/{id}/snapshot-schedule