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) (*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
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)

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

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