Create and start instance

post/instances

Body ParametersExpand Collapse

image: string

OCI image reference

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

maxLength63

cmd: optional array of string

Override image CMD (like docker run ). Omit to use image default.

credentials: optional map[object { inject, source } ]

Host-managed credential brokering policies keyed by guest-visible env var name. Those guest env vars receive mock placeholder values, while the real values remain host-scoped in the request env map and are only materialized on the mediated egress path according to each credential's source and inject rules.

inject: array of object { as, hosts }

as: object { format, header }

Current v1 transform shape. Header templating is supported now; other transform types (for example request signing) can be added in future revisions.

format: string

Template that must include ${value}.

hosts: optional array of string

Optional destination host patterns (api.example.com, *.example.com). Omit to allow injection on all destinations.

source: object { env }

env: string

Name of the real credential in the request env map. The guest-visible env var key can receive a mock placeholder, while the mediated egress path resolves that placeholder back to this real value only on the host.

devices: optional array of string

Device IDs or names to attach for GPU/PCI passthrough

disk_io_bps: optional string

Disk I/O rate limit (e.g., "100MB/s", "500MB/s"). Defaults to proportional share based on CPU allocation if configured.

entrypoint: optional array of string

Override image entrypoint (like docker run --entrypoint). Omit to use image default.

env: optional map[string]

Environment variables

gpu: optional object { profile }

GPU configuration for the instance

profile: optional string

vGPU profile name (e.g., "L40S-1Q"). Only used in vGPU mode.

hotplug_size: optional string

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

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

Hypervisor to use for this instance. Defaults to server configuration.

Accepts one of the following:

"cloud-hypervisor"

"firecracker"

"qemu"

"vz"

network: optional object { bandwidth_download, bandwidth_upload, egress, enabled }

Network configuration for the instance

bandwidth_download: optional string

Download bandwidth limit (external→VM, e.g., "1Gbps", "125MB/s"). Defaults to proportional share based on CPU allocation.

bandwidth_upload: optional string

Upload bandwidth limit (VM→external, e.g., "1Gbps", "125MB/s"). Defaults to proportional share based on CPU allocation.

egress: optional object { enabled, enforcement }

Host-mediated outbound network policy. Omit this object, or set enabled: false, to preserve normal direct outbound networking when network.enabled is true.

enabled: optional boolean

Whether to enable the mediated egress path. When false or omitted, the instance keeps normal direct outbound networking and host-managed credential rewriting is disabled.

enforcement: optional object { mode }

Egress enforcement policy applied when mediation is enabled.

mode: optional "all" or "http_https_only"

all (default) rejects direct non-mediated TCP egress from the VM, while http_https_only rejects direct egress only on TCP ports 80 and 443.

Accepts one of the following:

"all"

"http_https_only"

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

skip_guest_agent: optional boolean

Skip guest-agent installation during boot. When true, the exec and stat APIs will not work for this instance. The instance will still run, but remote command execution will be unavailable.

skip_kernel_headers: optional boolean

Skip kernel headers installation during boot for faster startup. When true, DKMS (Dynamic Kernel Module Support) will not work, preventing compilation of out-of-tree kernel modules (e.g., NVIDIA vGPU drivers). Recommended for workloads that don't need kernel module compilation.

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

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",
          "cmd": [
            "echo",
            "hello"
          ],
          "credentials": {
            "OUTBOUND_OPENAI_KEY": {
              "inject": [
                {
                  "as": {
                    "format": "Bearer ${value}",
                    "header": "Authorization"
                  },
                  "hosts": [
                    "api.openai.com",
                    "*.openai.com"
                  ]
                }
              ],
              "source": {
                "env": "OUTBOUND_OPENAI_KEY"
              }
            }
          },
          "devices": [
            "l4-gpu"
          ],
          "disk_io_bps": "100MB/s",
          "entrypoint": [
            "/bin/sh",
            "-c"
          ],
          "env": {
            "PORT": "3000",
            "NODE_ENV": "production"
          },
          "hotplug_size": "2GB",
          "hypervisor": "cloud-hypervisor",
          "overlay_size": "20GB",
          "size": "2GB",
          "skip_kernel_headers": true,
          "tags": {
            "team": "backend",
            "env": "staging"
          },
          "vcpus": 2
        }'

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