Skip to content
hypeman
Get started
API Reference
Instances

Create and start instance

post/instances

Create and start instance

Body ParametersExpand Collapse
image: string

OCI image reference

name: string

Human-readable name (lowercase letters, digits, and dashes only; cannot start or end with a dash)

maxLength63
env: optional map[string]

Environment variables

hotplug_size: optional string

Additional memory for hotplug (human-readable format like "3GB", "1G")

network: optional object { enabled }

Network configuration for the instance

enabled: optional boolean

Whether to attach instance to the default network

overlay_size: optional string

Writable overlay disk size (human-readable format like "10GB", "50G")

size: optional string

Base memory size (human-readable format like "1GB", "512MB", "2G")

vcpus: optional number

Number of virtual CPUs

volumes: optional array of VolumeMount { mount_path, volume_id, overlay, 2 more }

Volumes to attach to the instance at creation time

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

ReturnsExpand Collapse
Instance = object { id, created_at, image, 13 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" or "Running" or "Paused" or 4 more

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:
"Created"
"Running"
"Paused"
"Shutdown"
"Stopped"
"Standby"
"Unknown"
env: optional map[string]

Environment variables

has_snapshot: optional boolean

Whether a snapshot exists for this instance

hotplug_size: optional string

Hotplug memory size (human-readable)

network: optional object { enabled, ip, mac, name }

Network configuration of the instance

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)

name: optional string

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

Create and start instance
curl http://localhost:8080/instances \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $HYPEMAN_API_KEY" \
    -d '{
          "image": "docker.io/library/alpine:latest",
          "name": "my-workload-1",
          "env": {
            "PORT": "3000",
            "NODE_ENV": "production"
          },
          "hotplug_size": "2GB",
          "overlay_size": "20GB",
          "size": "2GB",
          "vcpus": 2
        }'
{
  "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
    }
  ]
}