Skip to content
hypeman
Get started
API Reference

Instances

List instances
client.Instances.List(ctx) (*[]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}
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
Start a stopped instance
client.Instances.Start(ctx, id) (*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
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)
  • 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:
const InstanceStateCreated InstanceState = "Created"
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

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 InstanceHypervisorQemu InstanceHypervisor = "qemu"
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
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 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}