fuse host register

Register a new compute host

fuse host register <id> [flags]

Adds a compute host to the orchestrator’s scheduler. <id> is a free-form, operator-supplied string and is the host’s primary key, use a readable one (for example prod-east-1).

Flags

Labels

--label key=value declares a label a Fusefile’s placement.labels selector can match on:

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

Labels are operator-declared and never probed from the host agent, the same trust model as --gpu-kind: Fuse does not check that the box really has NVMe. Keys and values must be alphanumeric with ., -, and _ inside, up to 63 characters. See Scheduling and placement.

Token verification

The --token is the host agent’s own token (FC_AGENT_TOKEN), not the orchestrator token. It is required for the firecracker backend: an empty token is almost always a mistake that would otherwise only surface at the first environment create as an opaque 401. Pass --no-verify to register an unauthenticated dev agent with no token.

At registration the orchestrator makes its first call to the host agent (the same call that probes capacity). If the agent rejects the token, registration is refused rather than persisting a host that can never be scheduled onto:

unauthorized: host agent at http://10.0.0.5:8090 rejected the token. this must be its FC_AGENT_TOKEN, not the orchestrator token
  re-run `fuse connect <url> --token <token>` with a valid token

If the agent is merely unreachable but you declared full capacity, the host still registers, with a warning.

Capacity probing

--cpus, --ram-mb, --storage-gb, --gpus, and --gpu-kind are optional. Leave any of them at its zero value (0, or empty for --gpu-kind) and the orchestrator probes the host agent for the real value instead of trusting an operator-declared guess. Pass one explicitly to override the probe, for a deliberate overcommit or a carve-out reserving part of the host for something else, a declared value above what the probe reports still registers successfully, with a warning printed rather than a rejection. A declared --gpu-kind that disagrees with the probe warns the same way.

Two things are never probed. --max-vms is scheduling policy rather than a hardware fact, so you always declare it. --mig-profile is operator-declared because MIG instances must be created on the host ahead of time, the agent reports whole devices but not the slices you carved out of them.

Per-device GPU inventory is the reverse case: it is probe-only. The agent reports each GPU’s UUID, model, PCI address, memory, driver version, and MIG mode, and there is no flag to declare or override that list.

If a value was left at 0 and the probe itself fails, for example because nothing is listening at --url, registration is refused rather than persisting a host with made-up capacity. Declare the values explicitly in that case.

# probe cpus/ram/storage from the host agent; only declare what's policy
fuse host register prod-east-1 \
  --url http://10.0.0.5:8090 \
  --region us-east \
  --max-vms 20

# override the probe with an explicit overcommit
fuse host register prod-east-1 \
  --url http://10.0.0.5:8090 \
  --cpus 32 \
  --ram-mb 65536 \
  --storage-gb 500 \
  --max-vms 20

GPU hosts

fuse host register gpu-1 \
  --url http://gpu-host:8091 \
  --token "$QEMU_AGENT_TOKEN" \
  --backend qemu \
  --gpus 1 \
  --gpu-kind a100 \
  --max-vms 4

--gpus requires --backend qemu; registering with --gpus set on a firecracker-backend host is rejected with gpus > 0 requires backend "qemu". The same applies to --mig-profile.

To offer fractional GPUs, declare the MIG instances you created on the host:

fuse host register gpu-1 \
  --url http://gpu-host:8091 \
  --token "$QEMU_AGENT_TOKEN" \
  --backend qemu \
  --mig-profile 1g.10gb=4 \
  --mig-profile 2g.20gb=2 \
  --max-vms 8

Each profile is validated in two places, so a typo fails at registration rather than silently advertising capacity that can never be filled. The CLI checks only the profile=count shape and the count itself: a value with no = or an empty key is rejected with invalid --mig-profile "...": expected profile=count (e.g. 1g.10gb=4), and a non-numeric or non-positive count with invalid --mig-profile "...": count must be a positive number.

The mig-parted grammar is checked server-side, not by the CLI, so a well-formed-but-meaningless profile such as --mig-profile foo=4 passes the client and is refused by the orchestrator:

invalid argument: mig_profiles: invalid MIG profile "foo" (expected mig-parted form like "1g.10gb")

Profile keys are lowercased.

A host may declare both --gpus and --mig-profile; the two are separate inventories and a MIG placement never consumes a whole device. See GPU host setup for the full VFIO/IOMMU bring-up.

Interactive mode

Omit --url in an interactive terminal to fill in the required fields via a form instead of flags. The form marks --cpus/--ram-mb/--storage-gb as “0 = probe from host agent” and --max-vms as “required, not probed” to match the flag behavior above. It prompts for GPU count and kind, but not for MIG profiles, register a MIG host with --mig-profile on the command line.

Output

On success, prints the registered host’s full detail, including any capacity warnings:

$ fuse host register prod-east-1 --url http://10.0.0.5:8090 --max-vms 20
registered host "prod-east-1"
id            prod-east-1
url           http://10.0.0.5:8090
region        -
backend       firecracker
state         active
cpus          0 / 16
ram mb        0 / 65536
storage gb    0 / 500
vms           0 / 20
last seen     ... (just now)
created       2026-01-15 10:00
updated       2026-01-15 10:00
warning: declared cpus (32) exceeds probed host capacity (16)
note: last_seen is set at registration and not refreshed; it is not a liveness signal

(The warning line only appears when a declared value actually exceeded the probe; a plain probe-everything registration prints no warnings. The note: line is unconditional and prints on every registration.)