Hosts

The machines Fuse schedules microVMs onto

A host is a machine running a host agent (fc-agent for Firecracker, or qemu-agent for GPU/QEMU), registered with the orchestrator. Register your hosts and Fuse’s scheduler places microVMs across them based on declared capacity and current allocation.

Registering a host

fuse host register <id> \
  --url http://10.0.0.5:8090 \
  --token "$FC_AGENT_TOKEN" \
  --region us-east \
  --backend firecracker \
  --cpus 16 --ram-mb 65536 --storage-gb 500 --max-vms 20

--token is the host agent’s own token, not the orchestrator token, and the CLI refuses a Firecracker registration without one, since an empty token would otherwise surface as an opaque 401 at the first environment create. Pass --no-verify instead if you are registering a genuinely unauthenticated dev agent.

The <id> is a free-form, operator-supplied string and is the host’s primary key; use something readable, like prod-east-1. GPU hosts additionally pass --gpus, --gpu-kind, and (for fractional GPUs) --mig-profile, and require --backend qemu. See Providers for the backend distinction.

Capacity and allocation

Every host tracks both a declared capacity (what you registered it with) and a live allocated figure (what’s currently in use by scheduled environments) across CPUs, RAM, storage, VM count, and (for GPU hosts) GPU devices. fuse host get <id> shows all of these, including the GPU and MIG pools. fuse host metrics <id> shows the CPU, RAM, storage, and VM-count figures with free headroom; its --json output carries the full capacity and allocated objects, GPU and MIG counts included.

Most of that capacity is probed from the host agent at registration time. The CPU count, RAM, storage, GPU count, GPU kind, and CPU architecture come back from the agent whenever you leave them at 0 or empty, and passing an explicit value overrides the probe instead, so a deliberate overcommit or carve-out still registers (with a warning when the declared value exceeds what was probed). The architecture (--arch, amd64 or arm64) is the one field where a declared-vs-probed contradiction is a hard error rather than a warning: a host whose declared arch disagrees with what its agent reports would receive images that cannot boot, so registration refuses it outright. A host with no arch at all counts as amd64. The per-device GPU list is always taken from the probe. The example above declares CPUs, RAM, and storage, so those three override the probe rather than being read from the agent. Two values are instead operator-declared, because they are policy or pre-created state rather than hardware facts the agent can observe: --max-vms is a ceiling you choose, and --mig-profile profile=count describes MIG instances that must already have been created on the host before Fuse ever sees them.

Labels

A host can carry operator-chosen labels that a Fusefile’s placement.labels selector matches on:

fuse host register build-3 --url https://build-3.internal:8080 \
  --max-vms 8 --label disk=nvme --label tier=build

Labels are declared, never probed. Fuse does not verify that disk=nvme describes the box, exactly as it does not verify --gpu-kind a100: they are your claim about the hardware, and a wrong claim sends work to the wrong place. Keys and values are alphanumeric with ., -, and _ inside, up to 63 characters.

fuse host get <id> shows a host’s labels. See Scheduling and placement for how the selector gate works.

A GPU host therefore tracks two independent pools: whole devices, and MIG instances counted per profile. They do not draw down on each other, a MIG placement never consumes a whole device. Because the GPU inventory is per-device rather than a bare number, the scheduler binds specific GPU UUIDs to a VM instead of just decrementing a count.

Cordon and uncordon

Cordoning a host marks it unschedulable. The scheduler stops placing new environments there, without touching what’s already running. This is the standard move before maintenance:

fuse host cordon <id>     # stop new placements
fuse host uncordon <id>   # resume scheduling

Removing a host

fuse host remove <id>

Deregistering a host is refused if any environments are still assigned to it; drain or destroy them first.

Selecting an active host in the CLI

Many CLI commands (like fuse environment list) scope themselves to an active host for convenience:

fuse host <id>       # select
fuse host            # show current selection

This is a CLI-local convenience, not an API concept: fuse environment create schedules orchestrator-wide regardless of the active host selection (use --region on create to influence placement instead).