fitctl

fitctl is a command-line tool for producing host-fit artifacts and returning failure exit codes when validation rejects a host.

It records observed host facts, derives policy-shaped host contracts, captures runtime state when required, and validates contracts against workload profiles.

The core workflow emits typed JSON artifacts. fitctl inspect prints structured text views for supported artifacts, and automation reads the JSON directly.

Use --fail-on-unfit or --require-fit when validation should control the process exit status. The validation report is written to stdout, and the exit status reflects the gate result.

Inspect a live host

fitctl survey | fitctl inspect

Summary
  Host
    Host alias: gpu-workstation-01
    Local stable identity: b6a4d2f1...91c7e840 (machine_id via etc_machine_id)

  Collection
    Collection mode: live
    Privilege level: limited

  Core
    CPU: AMD Ryzen Threadripper PRO 5975WX; x86_64; 64 logical cores; 32 physical cores
    Memory total: 256.00 GiB (274877906944 bytes)
    Storage: 6 block devices; classes solid_state=6
    Network: 3 interfaces; virtuality physical 2, virtual 1; kinds ethernet=2, loopback=1; 12 addresses; families ipv4, ipv6; default routes ipv4, ipv6; carrier-up physical 2/2; max 10000 Mbps

  Accelerators
    Observed GPUs: 2
    GPU 0000:65:00.0: NVIDIA RTX A6000; driver nvidia; operable
    GPU 0000:b3:00.0: NVIDIA RTX A6000; driver nvidia; operable

In the example above, fitctl survey emits a survey artifact and pipes it to fitctl inspect. fitctl inspect prints a structured text view of supported fitctl artifacts.

Make a fit decision

Run fitctl survey to collect local facts, fitctl contract to derive the host claim that policy allows, and fitctl validate to produce the fit decision. Each step emits a typed JSON artifact. fitctl inspect can print a text view, and automation can read the same JSON directly.

The example below uses the bundled host fixture, policy, and service profile from this repository so the example output is stable.

fitctl survey --fixture linux-bare-metal-like-v1 > host.survey.json

fitctl contract \
  --survey host.survey.json \
  --policy configs/policy/general_compute_default.v1.json \
  > host.contract.json

fitctl validate \
  --contract host.contract.json \
  --profile configs/service_profiles/general_compute_contract_only.v2.json \
  > validation.json

fitctl inspect --input validation.json

Summary
  Validation mode: contract_only
  Verdict: fit
  Operator posture: proceed
  Primary reason code: requirements_satisfied

Automate from the same artifact

The validation artifact is already the automation interface:

jq -r '.report.verdict' validation.json
jq -r '.report.primary_reason_code' validation.json

fit
requirements_satisfied

When a decision depends on live runtime conditions, collect state and pass --state to fitctl validate. This is typically required for accelerator visibility, allocatable memory, checked path capacity, and other runtime-only detail.

Use Installed Config

Installed binaries include bundled configuration files. Export them when you are not working from a repository checkout:

fitctl config export --out-dir fitctl-config

The exported files keep the same configs/... paths used in the examples.

Integration examples

• GitHub Actions GPU runner gate — validate CUDA runtime state before GPU-bound job steps run
• Host matrix selection — compare stored host artifacts against a state-aware memory profile

Core workflow commands and artifacts

Command	Produces	Purpose
fitctl survey	host-survey.v2	Observed local host facts
fitctl contract	host-contract.v2	Policy-shaped host claim
fitctl state	host-state.v2	Current runtime-sensitive facts
fitctl validate	validation-report.v2	Verdict, posture, and reason codes
fitctl classify	fitctl.batch-classification-report.v3	Batch comparison
fitctl config	configuration files	Bundled config list and export

The artifact you inspect is the artifact automation reads.

Run fitctl --help for the full command surface, including inspection, diffing, redaction, signing, verification, export, completion, and advanced configuration commands.

Compare hosts in batch

Create explicit CPU and GPU contracts, then print a batch report as a matrix:

fitctl survey --fixture linux-bare-metal-like-v1 > cpu.survey.json

fitctl contract \
  --survey cpu.survey.json \
  --policy configs/policy/general_compute_default.v1.json \
  > cpu.contract.json

fitctl survey --fixture linux-gpu-workstation-like-v1 > gpu.survey.json

fitctl contract \
  --survey gpu.survey.json \
  --policy configs/policy/gpu_compute_default.v1.json \
  > gpu.contract.json

fitctl classify \
  --contract cpu.contract.json \
  --contract gpu.contract.json \
  --profile configs/service_profiles/general_compute_no_gpu_contract_only.v2.json \
  --profile configs/service_profiles/gpu_preferred_with_general_compute_fallback_contract_only.v2.json \
  --profile configs/service_profiles/gpu_required_contract_only.v2.json \
  > batch.json

fitctl inspect --input batch.json --view matrix

Profile                     | Host        | Contract                | Verdict
----------------------------+-------------+-------------------------+---------------------
CPU only                    | cpu-host-01 | General compute default | fit
CPU only                    | gpu-host-01 | GPU compute default     | unfit
GPU preferred, CPU fallback | cpu-host-01 | General compute default | fit_with_degradation
GPU preferred, CPU fallback | gpu-host-01 | GPU compute default     | fit
GPU required                | cpu-host-01 | General compute default | unfit
GPU required                | gpu-host-01 | GPU compute default     | fit

Install

From crates.io:

cargo install fitctl --locked

Build from source

cargo build --workspace
./target/debug/fitctl --help
cargo install --path crates/fitctl-cli --locked

Documentation

• Configuration — policies and service profiles
• Contracts — contract derivation from survey evidence and policy
• Validation — validation, batch comparison, and fit decisions
• Accelerators — accelerator inventory, CUDA runtime detail, and the survey versus state split
• Artifacts — survey, contract, state, and validation-report artifacts
• Installed Configuration — bundled config listing and export
• Workload Reports — attaching fit artifacts to workload-run reports

Version history and release notes: GitHub Releases

License

Apache-2.0