Update instance properties

client.instances.update(, , ?): Instance { id, created_at, image, 19 more }

patch/instances/{id}

Update mutable properties of a running instance. Currently supports updating only the environment variables referenced by existing credential policies, enabling secret/key rotation without instance restart.

ParametersExpand Collapse

id: string

body: InstanceUpdateParams { env }

env?: Record<string, string>

Environment variables to update (merged with existing). Only keys referenced by the instance's existing credential source.env bindings are accepted. Use this to rotate real credential values without restarting the VM.

ReturnsExpand Collapse

Instance { id, created_at, image, 19 more }

id: string

Auto-generated unique identifier (CUID2 format)

created_at: string

Creation timestamp (RFC3339)

formatdate-time

image: string

OCI image reference

name: string

Human-readable name

state: "Created" | "Initializing" | "Running" | 5 more

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:

"Created"

"Initializing"

"Running"

"Paused"

"Shutdown"

"Stopped"

"Standby"

"Unknown"

disk_io_bps?: string

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

env?: Record<string, string>

Environment variables

exit_code?: number | null

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

exit_message?: string

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

gpu?: GPU { mdev_uuid, profile }

GPU information attached to the instance

mdev_uuid?: string

mdev device UUID

profile?: string

vGPU profile name

has_snapshot?: boolean

Whether a snapshot exists for this instance

hotplug_size?: string

Hotplug memory size (human-readable)

hypervisor?: "cloud-hypervisor" | "firecracker" | "qemu" | "vz"

Hypervisor running this instance

Accepts one of the following:

"cloud-hypervisor"

"firecracker"

"qemu"

"vz"

network?: Network { bandwidth_download, bandwidth_upload, enabled, 3 more }

Network configuration of the instance

bandwidth_download?: string

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

bandwidth_upload?: string

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

enabled?: boolean

Whether instance is attached to the default network

ip?: string | null

Assigned IP address (null if no network)

mac?: string | null

Assigned MAC address (null if no network)

name?: string

Network name (always "default" when enabled)

overlay_size?: string

Writable overlay disk size (human-readable)

size?: string

Base memory size (human-readable)

started_at?: string | null

Start timestamp (RFC3339)

formatdate-time

state_error?: string | null

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

stopped_at?: string | null

Stop timestamp (RFC3339)

formatdate-time

tags?: Record<string, string>

User-defined key-value tags.

vcpus?: number

Number of virtual CPUs

volumes?: Array<VolumeMount { mount_path, volume_id, overlay, 2 more } >

Volumes attached to the instance

mount_path: string

Path where volume is mounted in the guest

volume_id: string

Volume identifier

overlay?: boolean

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

overlay_size?: string

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

readonly?: boolean

Whether volume is mounted read-only

Update instance properties

import Hypeman from '@onkernel/hypeman';

const client = new Hypeman({
  apiKey: 'My API Key',
});

const instance = await client.instances.update('id');

console.log(instance.id);

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "created_at": "2025-01-15T10:30:00Z",
  "image": "docker.io/library/alpine:latest",
  "name": "my-workload-1",
  "state": "Created",
  "disk_io_bps": "100MB/s",
  "env": {
    "foo": "string"
  },
  "exit_code": 137,
  "exit_message": "killed by signal 9 (SIGKILL)",
  "gpu": {
    "mdev_uuid": "aa618089-8b16-4d01-a136-25a0f3c73123",
    "profile": "L40S-1Q"
  },
  "has_snapshot": false,
  "hotplug_size": "2GB",
  "hypervisor": "cloud-hypervisor",
  "network": {
    "bandwidth_download": "125MB/s",
    "bandwidth_upload": "125MB/s",
    "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",
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "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",
  "disk_io_bps": "100MB/s",
  "env": {
    "foo": "string"
  },
  "exit_code": 137,
  "exit_message": "killed by signal 9 (SIGKILL)",
  "gpu": {
    "mdev_uuid": "aa618089-8b16-4d01-a136-25a0f3c73123",
    "profile": "L40S-1Q"
  },
  "has_snapshot": false,
  "hotplug_size": "2GB",
  "hypervisor": "cloud-hypervisor",
  "network": {
    "bandwidth_download": "125MB/s",
    "bandwidth_upload": "125MB/s",
    "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",
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "vcpus": 2,
  "volumes": [
    {
      "mount_path": "/mnt/data",
      "volume_id": "vol-abc123",
      "overlay": true,
      "overlay_size": "1GB",
      "readonly": true
    }
  ]
}