Skip to content
hypeman
Get started
API Reference
Instances

Stop instance (graceful shutdown)

client.Instances.Stop(ctx, id) (*Instance, error)
post/instances/{id}/stop

Stop instance (graceful shutdown)

ParametersExpand Collapse
id string
ReturnsExpand 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

Stop instance (graceful shutdown)
package main

import (
  "context"
  "fmt"

  "github.com/onkernel/hypeman-go"
  "github.com/onkernel/hypeman-go/option"
)

func main() {
  client := hypeman.NewClient(
    option.WithAPIKey("My API Key"),
  )
  instance, err := client.Instances.Stop(context.TODO(), "id")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", instance.ID)
}

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "created_at": "2025-01-15T10:30:00Z",
  "image": "docker.io/library/alpine:latest",
  "name": "my-workload-1",
  "state": "Created",
  "env": {
    "foo": "string"
  },
  "has_snapshot": false,
  "hotplug_size": "2GB",
  "network": {
    "enabled": true,
    "ip": "192.168.100.10",
    "mac": "02:00:00:ab:cd:ef",
    "name": "default"
  },
  "overlay_size": "10GB",
  "size": "2GB",
  "started_at": "2025-01-15T10:30:05Z",
  "state_error": "failed to query VMM: connection refused",
  "stopped_at": "2025-01-15T12:30:00Z",
  "vcpus": 2,
  "volumes": [
    {
      "mount_path": "/mnt/data",
      "volume_id": "vol-abc123",
      "overlay": true,
      "overlay_size": "1GB",
      "readonly": true
    }
  ]
}
Returns Examples
{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "created_at": "2025-01-15T10:30:00Z",
  "image": "docker.io/library/alpine:latest",
  "name": "my-workload-1",
  "state": "Created",
  "env": {
    "foo": "string"
  },
  "has_snapshot": false,
  "hotplug_size": "2GB",
  "network": {
    "enabled": true,
    "ip": "192.168.100.10",
    "mac": "02:00:00:ab:cd:ef",
    "name": "default"
  },
  "overlay_size": "10GB",
  "size": "2GB",
  "started_at": "2025-01-15T10:30:05Z",
  "state_error": "failed to query VMM: connection refused",
  "stopped_at": "2025-01-15T12:30:00Z",
  "vcpus": 2,
  "volumes": [
    {
      "mount_path": "/mnt/data",
      "volume_id": "vol-abc123",
      "overlay": true,
      "overlay_size": "1GB",
      "readonly": true
    }
  ]
}