Register a device for passthrough

client.Devices.New(ctx, body) (*Device, error)

post/devices

ParametersExpand Collapse

body DeviceNewParams

PciAddress param.Field[string]

PCI address of the device (required, e.g., "0000:a2:00.0")

Name param.Field[string]optional

Optional globally unique device name. If not provided, a name is auto-generated from the PCI address (e.g., "pci-0000-a2-00-0")

ReturnsExpand Collapse

type Device struct{…}

ID string

Auto-generated unique identifier (CUID2 format)

BoundToVfio bool

Whether the device is currently bound to the vfio-pci driver, which is required for VM passthrough.

true: Device is bound to vfio-pci and ready for (or currently in use by) a VM. The device's native driver has been unloaded.
false: Device is using its native driver (e.g., nvidia) or no driver. Hypeman will automatically bind to vfio-pci when attaching to an instance.

CreatedAt Time

Registration timestamp (RFC3339)

formatdate-time

DeviceID string

PCI device ID (hex)

IommuGroup int64

IOMMU group number

PciAddress string

PCI address

Type DeviceType

Type of PCI device

Accepts one of the following:

const DeviceTypeGPU DeviceType = "gpu"

const DeviceTypePci DeviceType = "pci"

VendorID string

PCI vendor ID (hex)

AttachedTo stringoptional

Instance ID if attached

Name stringoptional

Device name (user-provided or auto-generated from PCI address)

Register a device for passthrough

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"),
  )
  device, err := client.Devices.New(context.TODO(), hypeman.DeviceNewParams{
    PciAddress: "0000:a2:00.0",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", device.ID)
}

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "bound_to_vfio": false,
  "created_at": "2025-01-15T10:00:00Z",
  "device_id": "27b8",
  "iommu_group": 82,
  "pci_address": "0000:a2:00.0",
  "type": "gpu",
  "vendor_id": "10de",
  "attached_to": null,
  "name": "l4-gpu"
}

Returns Examples

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "bound_to_vfio": false,
  "created_at": "2025-01-15T10:00:00Z",
  "device_id": "27b8",
  "iommu_group": 82,
  "pci_address": "0000:a2:00.0",
  "type": "gpu",
  "vendor_id": "10de",
  "attached_to": null,
  "name": "l4-gpu"
}