KEkernel

Register a device for passthrough

Changed on
post/devices

Request

  • Base URL
    http://localhost:4973
  • URL
    http://localhost:4973/devices
  • Auth
    HTTP bearer

Request body

namestring

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

pci_addressstring required

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

tagsTags

User-defined key-value tags.

Example request

{
  "name": "l4-gpu",
  "pci_address": "0000:a2:00.0",
  "tags": {
    "team": "backend",
    "env": "staging"
  }
}

Response

Device registered

idstring required

Auto-generated unique identifier (CUID2 format)

namestring

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

type'gpu' | 'pci' required

Type of PCI device

tagsTags

User-defined key-value tags.

pci_addressstring required

PCI address

vendor_idstring required

PCI vendor ID (hex)

device_idstring required

PCI device ID (hex)

iommu_groupinteger required

IOMMU group number

bound_to_vfioboolean required

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.
attached_tostring nullable

Instance ID if attached

created_atstring date-time required

Registration timestamp (RFC3339)

Example response

{
  "id": "tz4a98xxat96iws9zmbrgj3a",
  "name": "l4-gpu",
  "tags": {
    "team": "backend",
    "env": "staging"
  },
  "pci_address": "0000:a2:00.0",
  "vendor_id": "10de",
  "device_id": "27b8",
  "iommu_group": 82,
  "created_at": "2025-01-15T10:00:00Z"
}

Changes

  • d3b8f05f7a0fRevision changes
    • warning

      removed the request property

    • warning

      removed the optional property from the response with the status

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

  • 48572ed07140Revision changes
    • info

      added the new optional request property

    • info

      added the optional property to the response with the status