Skip to content
hypeman
Get started
API Reference

Instances

List instances
client.Instances.List(ctx, query) (*[]Instance, error)
get/instances
Create and start instance
client.Instances.New(ctx, body) (*Instance, error)
post/instances
Get instance details
client.Instances.Get(ctx, id) (*Instance, error)
get/instances/{id}
Update instance properties
client.Instances.Update(ctx, id, body) (*Instance, error)
patch/instances/{id}
Stop and delete instance
client.Instances.Delete(ctx, id) error
delete/instances/{id}
Put instance in standby (pause, snapshot, delete VMM)
client.Instances.Standby(ctx, id, body) (*Instance, error)
post/instances/{id}/standby
Restore instance from standby
client.Instances.Restore(ctx, id) (*Instance, error)
post/instances/{id}/restore
Fork an instance from stopped, standby, or running (with from_running=true)
client.Instances.Fork(ctx, id, body) (*Instance, error)
post/instances/{id}/fork
Start a stopped instance
client.Instances.Start(ctx, id, body) (*Instance, error)
post/instances/{id}/start
Stop instance (graceful shutdown)
client.Instances.Stop(ctx, id) (*Instance, error)
post/instances/{id}/stop
Stream instance logs (SSE)
client.Instances.Logs(ctx, id, query) (*string, error)
get/instances/{id}/logs
Get filesystem path info
client.Instances.Stat(ctx, id, query) (*PathInfo, error)
get/instances/{id}/stat
Get instance resource utilization stats
client.Instances.Stats(ctx, id) (*InstanceStats, error)
get/instances/{id}/stats
Wait for instance to reach a target state
client.Instances.Wait(ctx, id, query) (*WaitForStateResponse, error)
get/instances/{id}/wait
ModelsExpand Collapse
type Instance struct{…}
ID string

Auto-generated unique identifier (CUID2 format)

CreatedAt Time

Creation timestamp (RFC3339)

formatdate-time
Image string

OCI image reference

Name string

Human-readable name

State InstanceState

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:
const InstanceStateCreated InstanceState = "Created"
const InstanceStateInitializing InstanceState = "Initializing"
const InstanceStateRunning InstanceState = "Running"
const InstanceStatePaused InstanceState = "Paused"
const InstanceStateShutdown InstanceState = "Shutdown"
const InstanceStateStopped InstanceState = "Stopped"
const InstanceStateStandby InstanceState = "Standby"
const InstanceStateUnknown InstanceState = "Unknown"
DiskIoBps stringoptional

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

Env map[string, string]optional

Environment variables

ExitCode int64optional

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

ExitMessage stringoptional

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

GPU InstanceGPUoptional

GPU information attached to the instance

MdevUuid stringoptional

mdev device UUID

Profile stringoptional

vGPU profile name

HasSnapshot booloptional

Whether a snapshot exists for this instance

HotplugSize stringoptional

Hotplug memory size (human-readable)

Hypervisor InstanceHypervisoroptional

Hypervisor running this instance

Accepts one of the following:
const InstanceHypervisorCloudHypervisor InstanceHypervisor = "cloud-hypervisor"
const InstanceHypervisorFirecracker InstanceHypervisor = "firecracker"
const InstanceHypervisorQemu InstanceHypervisor = "qemu"
const InstanceHypervisorVz InstanceHypervisor = "vz"
Network InstanceNetworkoptional

Network configuration of the instance

BandwidthDownload stringoptional

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

BandwidthUpload stringoptional

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

Enabled booloptional

Whether instance is attached to the default network

IP stringoptional

Assigned IP address (null if no network)

Mac stringoptional

Assigned MAC address (null if no network)

Name stringoptional

Network name (always "default" when enabled)

OverlaySize stringoptional

Writable overlay disk size (human-readable)

Size stringoptional

Base memory size (human-readable)

SnapshotPolicy SnapshotPolicyoptional
Compression SnapshotCompressionConfigoptional
Enabled bool

Enable snapshot memory compression

Algorithm SnapshotCompressionConfigAlgorithmoptional

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

Accepts one of the following:
const SnapshotCompressionConfigAlgorithmZstd SnapshotCompressionConfigAlgorithm = "zstd"
const SnapshotCompressionConfigAlgorithmLz4 SnapshotCompressionConfigAlgorithm = "lz4"
Level int64optional

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
StartedAt Timeoptional

Start timestamp (RFC3339)

formatdate-time
StateError stringoptional

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

StoppedAt Timeoptional

Stop timestamp (RFC3339)

formatdate-time
Tags map[string, string]optional

User-defined key-value tags.

Vcpus int64optional

Number of virtual CPUs

Volumes []VolumeMountoptional

Volumes attached to the instance

MountPath string

Path where volume is mounted in the guest

VolumeID string

Volume identifier

Overlay booloptional

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

OverlaySize stringoptional

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

Readonly booloptional

Whether volume is mounted read-only

type InstanceStats struct{…}

Real-time resource utilization statistics for a VM instance

AllocatedMemoryBytes int64

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

formatint64
AllocatedVcpus int64

Number of vCPUs allocated to the VM

CPUSeconds float64

Total CPU time consumed by the VM hypervisor process in seconds

formatdouble
InstanceID string

Instance identifier

InstanceName string

Instance name

MemoryRssBytes int64

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

formatint64
MemoryVmsBytes int64

Virtual Memory Size - total virtual memory allocated in bytes

formatint64
NetworkRxBytes int64

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

formatint64
NetworkTxBytes int64

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

formatint64
MemoryUtilizationRatio float64optional

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

formatdouble
type PathInfo struct{…}
Exists bool

Whether the path exists

Error stringoptional

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.

IsDir booloptional

True if this is a directory

IsFile booloptional

True if this is a regular file

Mode int64optional

File mode (Unix permissions)

Size int64optional

File size in bytes

formatint64
type PortMapping struct{…}
GuestPort int64

Port in the guest VM

HostPort int64

Port on the host

Protocol PortMappingProtocoloptional
Accepts one of the following:
const PortMappingProtocolTcp PortMappingProtocol = "tcp"
const PortMappingProtocolUdp PortMappingProtocol = "udp"
type SetSnapshotScheduleRequest struct{…}
Interval string

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

Retention SnapshotScheduleRetention

At least one of max_count or max_age must be provided.

MaxAge stringoptional

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

MaxCount int64optional

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

minimum0
Metadata map[string, string]optional

User-defined key-value tags.

NamePrefix stringoptional

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

maxLength47
type SnapshotPolicy struct{…}
Compression SnapshotCompressionConfigoptional
Enabled bool

Enable snapshot memory compression

Algorithm SnapshotCompressionConfigAlgorithmoptional

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

Accepts one of the following:
const SnapshotCompressionConfigAlgorithmZstd SnapshotCompressionConfigAlgorithm = "zstd"
const SnapshotCompressionConfigAlgorithmLz4 SnapshotCompressionConfigAlgorithm = "lz4"
Level int64optional

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
type SnapshotSchedule struct{…}
CreatedAt Time

Schedule creation timestamp.

formatdate-time
InstanceID string

Source instance ID.

Interval string

Snapshot interval (Go duration format).

NextRunAt Time

Next scheduled run time.

formatdate-time
Retention SnapshotScheduleRetention

Automatic cleanup policy for scheduled snapshots.

MaxAge stringoptional

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

MaxCount int64optional

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

minimum0
UpdatedAt Time

Schedule update timestamp.

formatdate-time
LastError stringoptional

Last schedule run error, if any.

LastRunAt Timeoptional

Last schedule execution time.

formatdate-time
LastSnapshotID stringoptional

Snapshot ID produced by the last successful run.

Metadata map[string, string]optional

User-defined key-value tags.

NamePrefix stringoptional

Optional prefix used for generated scheduled snapshot names.

type SnapshotScheduleRetention struct{…}

Automatic cleanup policy for scheduled snapshots.

MaxAge stringoptional

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

MaxCount int64optional

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

minimum0
type VolumeMount struct{…}
MountPath string

Path where volume is mounted in the guest

VolumeID string

Volume identifier

Overlay booloptional

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

OverlaySize stringoptional

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

Readonly booloptional

Whether volume is mounted read-only

type WaitForStateResponse struct{…}
State WaitForStateResponseState

Current instance state when the wait completed

Accepts one of the following:
const WaitForStateResponseStateCreated WaitForStateResponseState = "Created"
const WaitForStateResponseStateInitializing WaitForStateResponseState = "Initializing"
const WaitForStateResponseStateRunning WaitForStateResponseState = "Running"
const WaitForStateResponseStatePaused WaitForStateResponseState = "Paused"
const WaitForStateResponseStateShutdown WaitForStateResponseState = "Shutdown"
const WaitForStateResponseStateStopped WaitForStateResponseState = "Stopped"
const WaitForStateResponseStateStandby WaitForStateResponseState = "Standby"
const WaitForStateResponseStateUnknown WaitForStateResponseState = "Unknown"
TimedOut bool

Whether the timeout expired before the target state was reached

StateError stringoptional

Error message when derived state is Unknown

InstancesVolumes

Attach volume to instance
client.Instances.Volumes.Attach(ctx, volumeID, params) (*Instance, error)
post/instances/{id}/volumes/{volumeId}
Detach volume from instance
client.Instances.Volumes.Detach(ctx, volumeID, body) (*Instance, error)
delete/instances/{id}/volumes/{volumeId}

InstancesSnapshots

Create a snapshot for an instance
client.Instances.Snapshots.New(ctx, id, body) (*Snapshot, error)
post/instances/{id}/snapshots
Restore an instance from a snapshot in-place
client.Instances.Snapshots.Restore(ctx, snapshotID, params) (*Instance, error)
post/instances/{id}/snapshots/{snapshotId}/restore

InstancesSnapshot Schedule

Get snapshot schedule for an instance
client.Instances.SnapshotSchedule.Get(ctx, id) (*SnapshotSchedule, error)
get/instances/{id}/snapshot-schedule
Create or update snapshot schedule for an instance
client.Instances.SnapshotSchedule.Update(ctx, id, body) (*SnapshotSchedule, error)
put/instances/{id}/snapshot-schedule
Delete snapshot schedule for an instance
client.Instances.SnapshotSchedule.Delete(ctx, id) error
delete/instances/{id}/snapshot-schedule