API Reference

Instances

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create and start instance

client.Instances.New(ctx, body) (*Instance, error)

post/instances

Create and start instance

ParametersExpand Collapse

body InstanceNewParams

Image param.Field[string]

OCI image reference

Name param.Field[string]

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

maxLength63

Cmd param.Field[[]string]optional

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

Credentials param.Field[map[string, InstanceNewParamsCredential]]optional

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 []InstanceNewParamsCredentialInject

As InstanceNewParamsCredentialInjectAs

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

Header string

Header name to set/mutate for matching outbound requests.

Hosts []stringoptional

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

Source InstanceNewParamsCredentialSource

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 param.Field[[]string]optional

Device IDs or names to attach for GPU/PCI passthrough

DiskIoBps param.Field[string]optional

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

Entrypoint param.Field[[]string]optional

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

Env param.Field[map[string, string]]optional

Environment variables

GPU param.Field[InstanceNewParamsGPU]optional

GPU configuration for the instance

Profile stringoptional

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

HotplugSize param.Field[string]optional

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

Hypervisor param.Field[InstanceNewParamsHypervisor]optional

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

const InstanceNewParamsHypervisorCloudHypervisor InstanceNewParamsHypervisor = "cloud-hypervisor"

const InstanceNewParamsHypervisorFirecracker InstanceNewParamsHypervisor = "firecracker"

const InstanceNewParamsHypervisorQemu InstanceNewParamsHypervisor = "qemu"

const InstanceNewParamsHypervisorVz InstanceNewParamsHypervisor = "vz"

Network param.Field[InstanceNewParamsNetwork]optional

Network configuration for the instance

BandwidthDownload stringoptional

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

BandwidthUpload stringoptional

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

Egress InstanceNewParamsNetworkEgressoptional

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

Enabled booloptional

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 InstanceNewParamsNetworkEgressEnforcementoptional

Egress enforcement policy applied when mediation is enabled.

Mode stringoptional

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:

const InstanceNewParamsNetworkEgressEnforcementModeAll InstanceNewParamsNetworkEgressEnforcementMode = "all"

const InstanceNewParamsNetworkEgressEnforcementModeHTTPHTTPSOnly InstanceNewParamsNetworkEgressEnforcementMode = "http_https_only"

Enabled booloptional

Whether to attach instance to the default network

OverlaySize param.Field[string]optional

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

Size param.Field[string]optional

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

SkipGuestAgent param.Field[bool]optional

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.

SkipKernelHeaders param.Field[bool]optional

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 param.Field[map[string, string]]optional

User-defined key-value tags.

Vcpus param.Field[int64]optional

Number of virtual CPUs

Volumes param.Field[[]VolumeMount]optional

Volumes to attach to the instance at creation time

MountPath string

Path where volume is mounted in the guest

VolumeID string

Volume identifier

Overlay booloptional

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

OverlaySize stringoptional

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

Readonly booloptional

Whether volume is mounted read-only

ReturnsExpand Collapse

type Instance struct{…}

ID string

Auto-generated unique identifier (CUID2 format)

CreatedAt Time

Creation timestamp (RFC3339)

formatdate-time

Image string

OCI image reference

Name string

Human-readable name

State InstanceState

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:

const InstanceStateCreated InstanceState = "Created"

const InstanceStateInitializing InstanceState = "Initializing"

const InstanceStateRunning InstanceState = "Running"

const InstanceStatePaused InstanceState = "Paused"

const InstanceStateShutdown InstanceState = "Shutdown"

const InstanceStateStopped InstanceState = "Stopped"

const InstanceStateStandby InstanceState = "Standby"

const InstanceStateUnknown InstanceState = "Unknown"

DiskIoBps stringoptional

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

Env map[string, string]optional

Environment variables

ExitCode int64optional

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

ExitMessage stringoptional

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

GPU InstanceGPUoptional

GPU information attached to the instance

MdevUuid stringoptional

mdev device UUID

Profile stringoptional

vGPU profile name

HasSnapshot booloptional

Whether a snapshot exists for this instance

HotplugSize stringoptional

Hotplug memory size (human-readable)

Hypervisor InstanceHypervisoroptional

Hypervisor running this instance

Accepts one of the following:

const InstanceHypervisorCloudHypervisor InstanceHypervisor = "cloud-hypervisor"

const InstanceHypervisorFirecracker InstanceHypervisor = "firecracker"

const InstanceHypervisorQemu InstanceHypervisor = "qemu"

const InstanceHypervisorVz InstanceHypervisor = "vz"

Network InstanceNetworkoptional

Network configuration of the instance

BandwidthDownload stringoptional

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

BandwidthUpload stringoptional

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

Enabled booloptional

Whether instance is attached to the default network

IP stringoptional

Assigned IP address (null if no network)

Mac stringoptional

Assigned MAC address (null if no network)

Name stringoptional

Network name (always "default" when enabled)

OverlaySize stringoptional

Writable overlay disk size (human-readable)

Size stringoptional

Base memory size (human-readable)

StartedAt Timeoptional

Start timestamp (RFC3339)

formatdate-time

StateError stringoptional

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

StoppedAt Timeoptional

Stop timestamp (RFC3339)

formatdate-time

Tags map[string, string]optional

User-defined key-value tags.

Vcpus int64optional

Number of virtual CPUs

Volumes []VolumeMountoptional

Volumes attached to the instance

MountPath string

Path where volume is mounted in the guest

VolumeID string

Volume identifier

Overlay booloptional

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

OverlaySize stringoptional

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

Readonly booloptional

Whether volume is mounted read-only

Create and start instance

Go

HTTP

TypeScript

Go

package main

import (
  "context"
  "fmt"

  "github.com/kernel/hypeman-go"
  "github.com/kernel/hypeman-go/option"
)

func main() {
  client := hypeman.NewClient(
    option.WithAPIKey("My API Key"),
  )
  instance, err := client.Instances.New(context.TODO(), hypeman.InstanceNewParams{
    Image: "docker.io/library/alpine:latest",
    Name: "my-workload-1",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", instance.ID)
}

200 example

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

200 example

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