Skip to content
hypeman
Get started
API Reference
Instances

Fork an instance from stopped, standby, or running (with from_running=true)

client.instances.fork(stringid, InstanceForkParams { name, from_running, target_state } body, RequestOptionsoptions?): Instance { id, created_at, image, 19 more }
post/instances/{id}/fork

Fork an instance from stopped, standby, or running (with from_running=true)

ParametersExpand Collapse
id: string
body: InstanceForkParams { name, from_running, target_state }
name: string

Name for the forked instance (lowercase letters, digits, and dashes only; cannot start or end with a dash)

maxLength63
from_running?: boolean

Allow forking from a running source instance. When true and source is Running, the source is put into standby, forked, then restored back to Running.

target_state?: "Stopped" | "Standby" | "Running"

Optional final state for the forked instance. Default is the source instance state at fork time. For example, forking from Running defaults the fork result to Running.

Accepts one of the following:
"Stopped"
"Standby"
"Running"
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

Fork an instance from stopped, standby, or running (with from_running=true)
import Hypeman from '@onkernel/hypeman';

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

const instance = await client.instances.fork('id', { name: 'my-workload-1-fork' });

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