Hosts

Registering and managing the compute hosts the scheduler places VMs onto

client.hosts registers and manages the compute hosts the scheduler places microVMs onto. Register a host, letting the orchestrator probe its real hardware capacity rather than trusting a guess:

const host = await client.hosts.register({
  id: "prod-east-1",
  url: "http://10.0.0.5:8090",
  token: agentToken,
  region: "us-east",
  backend: "firecracker",
  capacity: { cpus: 0, ram_mb: 0, storage_gb: 0, vm_count: 20 }, // 0 = probe
});
for (const w of host.warnings ?? []) {
  console.warn(w);
}

id is a free-form, operator-supplied string and doubles as the host’s primary key. backend defaults to "firecracker" if omitted; only "qemu" hosts may register with capacity.gpus > 0.
capacity.cpus, ram_mb, and storage_gb are optional hardware facts: leaving any at 0 (as above) has the orchestrator probe the host agent for the real value instead of trusting a guess. Pass one explicitly to override the probe, for a deliberate overcommit or carve-out, a declared value above what the probe reports still registers, with a warning rather than a rejection. If the host’s provider doesn’t support probing at all and a value was left at 0, registration throws a FuseApiError with status === 400 and code === "invalid_argument", declare all three explicitly in that case. If a probe is attempted and fails while cpus, ram_mb, and storage_gb are not all declared, you get status === 502 and code === "internal" instead.
the capacity probe doubles as an auth probe, it is the first call the orchestrator makes to the host agent with the supplied token. If the agent rejects it, registration fails with status === 502 and code === "unauthorized" regardless of whether capacity was declared. token must be the agent’s own FC_AGENT_TOKEN, not the orchestrator token.
capacity.vm_count is scheduling policy, not something a host can report on its own, so it’s never probed and is always required.
host.warnings is only ever populated on this call’s response, non-fatal notices like a declared value exceeding what was probed.

Everything else

Method	Purpose
`list()`	List every registered host with its declared `capacity` and live `allocated` figures.
`get(hostId)`	Fetch one host by ID.
`cordon(hostId)` / `uncordon(hostId)`	Stop or resume scheduling new environments onto the host, without touching what’s already running.
`deregister(hostId)`	Remove the host. Throws a `FuseApiError` with `status === 409` and `code === "conflict"` if environments are still assigned to it.

Deregistering a host that still has environments assigned returns 409/conflict, so isConflict(err) reports true and you can branch on it rather than on the error message (host <id> still has vm <id> assigned). Drain the host’s environments before removing it.

Host.state is one of active, cordoned, or draining. Host.last_seen is set once at registration and never refreshed, it is not a liveness signal. These mirror the HTTP API one to one.