Skip to content
Fuse
Esc
↑↓navigate↵open⌘Jpreview

Register or update a host

Requires the master token: this endpoint takes a caller-supplied agent URL and token and can replace the provider details of an existing host ID, so it decides where the orchestrator sends every subsequent VM operation. An API-key principal gets 403.

The url is validated before anything is dialled: http or https only, no embedded credentials, no query string, no fragment. A rejected URL is never probed or persisted (400).

Registers a host. Re-registering an existing ID is a full replacement, not a patch: the handler builds a fresh host record from the request alone and overwrites the stored entry. Beyond URL, token, region, and capacity, that also (a) overwrites backend, (b) resets state to active — silently uncordoning a cordoned host, (c) zeroes the allocated counters even while VMs are still placed on the host, and that zeroed record is persisted, and (d) resets created_at to now. Do not use this endpoint to tweak one field of a live host; (b) and (c) are scheduling side effects that can lead to overcommit.

The capacity probe against the host agent doubles as an auth check: a token the agent rejects fails registration with 502, while an unreachable agent only blocks when cpus/ram_mb/storage_gb were not all declared (otherwise the host registers with a warning, so pre-provisioning an unreachable host still works). The response capacity reflects resolved (probed or overridden) values, never the raw zeros sent, and warnings is populated only on this response.

POST/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.
or
fuse_sessionAPI key · cookierequired
HttpOnly session cookie set by POST /login for browser callers. Consulted only when no Authorization header is present.
Request body
requiredapplication/json
idstringrequired
urlstringrequired
tokenstring
regionstring
backendstring
Virtualization backend. Defaults to "firecracker". Only "qemu" hosts may register with capacity.gpus > 0.
Allowed:firecrackerqemu
labelsobject
Operator-declared key/value pairs a spec's placement labels can select on. Declared, never probed: they are a claim about the box, like capacity.gpu_kind.
capacityobjectrequired
cpus/ram_mb/storage_gb/gpus left at 0 and an empty gpu_kind are filled from the host agent's capacity probe. Positive declared values override the probe; exceeding the probed value (or declaring a gpu_kind that differs from the probed one) succeeds with a note in HostInfo.warnings. vm_count is scheduling policy, not a hardware fact: always required, never probed.
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.
Responses
201Host registered.
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
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.
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.
400Malformed request.
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.
500Unexpected server error.
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.
501Host registration is disabled — the orchestrator was started without a provider factory.
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.
502The capacity probe against the host agent failed. Either the agent rejected the token (code `unauthorized` — the token must be the agent's own `FC_AGENT_TOKEN`, not the orchestrator token) or the agent was unreachable while cpus/ram_mb/storage_gb were not all declared explicitly (code `internal`).
errorobjectrequired
Show properties
codestringrequired
Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.
Request
curl -X POST "http://localhost:8080/v1/hosts" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "string",
  "url": "string",
  "token": "string",
  "region": "string",
  "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"
      }
    ]
  }
}'
Response
{
  "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"
  ]
}