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

post/instances/{id}/fork

Path ParametersExpand Collapse

id: string

Body ParametersExpand Collapse

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

maxLength63

from_running: optional 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: optional "Stopped" or "Standby" or "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 = object { 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

Human-readable name

state: "Created" or "Initializing" or "Running" or 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: optional string

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

env: optional map[string]

Environment variables

exit_code: optional number

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

exit_message: optional string

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

gpu: optional object { mdev_uuid, profile }

GPU information attached to the instance

mdev_uuid: optional string

mdev device UUID

profile: optional string

vGPU profile name

has_snapshot: optional boolean

Whether a snapshot exists for this instance

hotplug_size: optional string

Hotplug memory size (human-readable)

hypervisor: optional "cloud-hypervisor" or "firecracker" or "qemu" or "vz"

Hypervisor running this instance

Accepts one of the following:

"cloud-hypervisor"

"firecracker"

"qemu"

"vz"

network: optional object { bandwidth_download, bandwidth_upload, enabled, 3 more }

Network configuration of the instance

bandwidth_download: optional string

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

bandwidth_upload: optional string

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

enabled: optional boolean

Whether instance is attached to the default network

ip: optional string

Assigned IP address (null if no network)

mac: optional string

Assigned MAC address (null if no network)

Network name (always "default" when enabled)

overlay_size: optional string

Writable overlay disk size (human-readable)

size: optional string

Base memory size (human-readable)

started_at: optional string

Start timestamp (RFC3339)

formatdate-time

state_error: optional string

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

stopped_at: optional string

Stop timestamp (RFC3339)

formatdate-time

tags: optional map[string]

User-defined key-value tags.

vcpus: optional number

Number of virtual CPUs

volumes: optional array of 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: optional boolean

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

overlay_size: optional string

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

readonly: optional boolean

Whether volume is mounted read-only

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

curl http://localhost:8080/instances/$ID/fork \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $HYPEMAN_API_KEY" \
    -d '{
          "name": "my-workload-1-fork",
          "target_state": "Running"
        }'

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