List registered hosts

GET/v1/hosts

Authorization

AuthorizationBearer token · headerrequired

`Authorization: Bearer <token>` — either the static master token (`ORCH_AUTH_TOKEN`) or a revocable API key issued via /v1/api-keys (API keys require Postgres; without a database only the master token is accepted). Master-only surfaces (exec, attach, API key management) refuse API keys with 403. **Authentication can be disabled entirely.** When neither `ORCH_AUTH_TOKEN` nor an API key store (`DATABASE_URL`) is configured — the default local-development posture — the bearer middleware becomes a pass-through: every operation this document marks as secured is reachable with no credentials, requests carry no principal, and master-only surfaces therefore admit everyone. Never run that configuration on a reachable network; set `ORCH_REQUIRE_AUTH=true` to make the orchestrator refuse to start without a master token.

fuse_sessionAPI key · cookierequired

HttpOnly session cookie set by POST /login for browser callers. Consulted only when no Authorization header is present.

Responses

200Host list.

hostsHostInfo[]required

Show properties

Array of HostInfo

idstringrequired

urlstringrequired

regionstring

statestringrequired

`draining` means cordoned with eviction pending; drain automation is not yet implemented.

Allowed:activecordoneddraining

backendstring

Virtualization backend the host runs.

Allowed:firecrackerqemu

labelsobject

Operator-declared placement labels for this host.

capacityHostCapacityrequired

On responses (HostInfo.capacity / HostInfo.allocated) the four scalar fields cpus/ram_mb/storage_gb/vm_count are always serialized. On registration requests only vm_count is required; the other scalars may be omitted to have them probed from the host agent.

Show properties

cpusinteger

ram_mbinteger

storage_gbinteger

vm_countintegerrequired

Max concurrent VMs.

gpusinteger

Count of whole GPU devices. Only qemu-backed hosts may report a non-zero value.

gpu_kindstring

GPU model (e.g. "a100"). Empty when gpus is 0.

mig_profilesobject

Fractional GPU capacity: MIG instance count by profile name (e.g. {"1g.10gb": 4}). Requires backend "qemu". Independent of the whole-device gpus counter (decision D5). Keys are lowercased on registration and must be mig-parted profile names (e.g. "1g.10gb") with positive counts; invalid entries are rejected with 400.

gpu_devicesGPUDevice[]

Per-device GPU inventory probed from the host agent. Probe-only: values sent in a register request are discarded. Populated only on capacity (never allocated) of qemu-backed hosts. `gpus` and the length of `gpu_devices` may disagree: the host agent emits at most one entry per IOMMU group, so a group holding several GPUs contributes one entry while each card still counts toward `gpus`. Treat `gpus` as the schedulable count and `gpu_devices` as best-effort detail.

Show properties

Array of GPUDevice

uuidstring

modelstring

E.g. "NVIDIA A100-SXM4-40GB".

pci_bus_idstring

memory_mbinteger

driver_versionstring

cuda_versionstring

Reserved — not currently populated by the host agent.

compute_capstring

mig_capableboolean

mig_modestring

E.g. "Enabled".

iommu_groupstring

Reserved — not currently populated by the host agent.

allocatedHostCapacityrequired

Show properties

cpusinteger

ram_mbinteger

storage_gbinteger

vm_countintegerrequired

Max concurrent VMs.

gpusinteger

Count of whole GPU devices. Only qemu-backed hosts may report a non-zero value.

gpu_kindstring

GPU model (e.g. "a100"). Empty when gpus is 0.

mig_profilesobject

gpu_devicesGPUDevice[]

Show properties

Array of GPUDevice

uuidstring

modelstring

E.g. "NVIDIA A100-SXM4-40GB".

pci_bus_idstring

memory_mbinteger

driver_versionstring

cuda_versionstring

Reserved — not currently populated by the host agent.

compute_capstring

mig_capableboolean

mig_modestring

E.g. "Enabled".

iommu_groupstring

Reserved — not currently populated by the host agent.

last_seenstring<date-time>required

created_atstring<date-time>required

updated_atstring<date-time>required

warningsstring[]

Non-fatal registration notices (e.g. a declared capacity value that exceeded what was probed from the host agent). Only ever populated on the response to POST /v1/hosts.

Request

curl -X GET "http://localhost:8080/v1/hosts" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("http://localhost:8080/v1/hosts", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.get(
    "http://localhost:8080/v1/hosts",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "hosts": [
    {
      "id": "string",
      "url": "string",
      "region": "string",
      "state": "active",
      "backend": "firecracker",
      "labels": {},
      "capacity": {
        "cpus": 0,
        "ram_mb": 0,
        "storage_gb": 0,
        "vm_count": 0,
        "gpus": 0,
        "gpu_kind": "string",
        "mig_profiles": {},
        "gpu_devices": [
          {
            "uuid": "string",
            "model": "string",
            "pci_bus_id": "string",
            "memory_mb": 0,
            "driver_version": "string",
            "cuda_version": "string",
            "compute_cap": "string",
            "mig_capable": true,
            "mig_mode": "string",
            "iommu_group": "string"
          }
        ]
      },
      "allocated": {
        "cpus": 0,
        "ram_mb": 0,
        "storage_gb": 0,
        "vm_count": 0,
        "gpus": 0,
        "gpu_kind": "string",
        "mig_profiles": {},
        "gpu_devices": [
          {
            "uuid": "string",
            "model": "string",
            "pci_bus_id": "string",
            "memory_mb": 0,
            "driver_version": "string",
            "cuda_version": "string",
            "compute_cap": "string",
            "mig_capable": true,
            "mig_mode": "string",
            "iommu_group": "string"
          }
        ]
      },
      "last_seen": "2024-01-01T00:00:00Z",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "warnings": [
        "string"
      ]
    }
  ]
}