Commands / kosa8 validate oq
kosa8 validate oq
Run an Operational Qualification protocol in a clone of a validated snapshot
Usage
kosa8 oq SNAPSHOT --protocol FILE
Runs each step of a declared test protocol (YAML or JSON: a command, where to run it, and the expected exit code and output) inside a sandbox restored from SNAPSHOT under a new name, so the validated state is never modified. Records every step's result with timestamps and output digests, the protocol file by digest, and the snapshot's seal as verified at restore. The clone is removed afterwards unless --keep-clone.
A protocol (docs/design/gxp-validation.md has the full format):
id: OQ-STATS-001 version: "1.0" title: R environment operational qualification image: r-base:4.4.1 steps: - id: OQ-01 title: R reports the validated version requirement: URS-12 run: [R, --version] expect: {exit: 0, stdout_regex: 'R version 4\.4\.1'}
Options
| Flag | Type | What it does | Default |
|---|---|---|---|
--html | bool | also render RECORD.html | — |
--keep-clone | bool | leave the clone the steps ran in, for investigating a failure | — |
-o, --out | string | record package: .tar for a tar, else a directory (default <RECORD-ID>.tar) | — |
-p, --protocol | string | the OQ protocol to execute (YAML or JSON) | — |
--signer | string | printed name of the package signer | — |
--signer-key | string | sign the package with this Ed25519 key file instead of the machine's key | — |
Example
kosa8 validate oq stats-validated --protocol oq-stats.yaml --out oq-2026-09.tar