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

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"

Env map[string, string]optional

Environment variables

HasSnapshot booloptional

Whether a snapshot exists for this instance

HotplugSize stringoptional

Hotplug memory size (human-readable)

Network InstanceNetworkoptional

Network configuration of the instance

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