Kova runs release-shaped OpenClaw scenarios on real machines and records the evidence. It is for maintainers and agents validating install, upgrade, gateway, agent, plugin, TUI, MCP, browser, and long-running behavior before a release.
Kova requires Node.js 22 or newer. Real scenarios use OCM to provision isolated OpenClaw environments; the installer can install it at the same time:
curl -fsSL https://raw.githubusercontent.com/openclaw/Kova/main/install.sh | KOVA_INSTALL_OCM=1 bashThis installs Kova under ~/.kova and links kova into ~/.local/bin.
To run Kova from a source checkout instead:
git clone https://github.com/openclaw/Kova.git
cd Kova
npm ciUse node bin/kova.mjs in place of kova in a source checkout.
Preview the smoke matrix without changing an OpenClaw environment:
kova matrix plan --profile smoke --target runtime:stableThe plan resolves the current scenarios, states, and evidence obligations for the selected target in a few seconds.
Confirm the lab is healthy, then execute the matrix against an existing OCM runtime:
kova self-check
kova matrix run --profile smoke --target runtime:stable --executeKova uses deterministic mock model auth by default. Run kova setup when a
scenario needs live provider credentials.
Kova evaluates a concrete product path rather than treating a successful command as proof:
surface × user state × target runtime × platform → evidence → verdict
Surfaces, states, scenarios, profiles, process roles, and thresholds are declarative JSON contracts. OCM creates and controls the disposable lab; OpenClaw remains the product under test.
| Selector | What Kova tests |
|---|---|
npm:<version> |
A published OpenClaw version |
release:<name> |
A published release track such as stable or beta |
runtime:<name> |
An existing OCM runtime |
local-build:<path> |
A release-shaped build from an OpenClaw checkout |
Profiles turn those targets into repeatable matrices. Start with smoke, use
release for the ship gate, and use focused profiles for diagnostics, upgrades,
plugins, soak, or adversarial behavior. See the CLI reference
for the current commands, selectors, and profiles.
Kova records readiness, health, command results, CPU and RSS by process role, OpenClaw diagnostic spans, provider timing, cleanup, and artifacts. Repeated runs produce median, p95, maximum, and variance measurements; reviewed baselines make regressions visible separately from functional failures.
Every human-facing command renders a dashboard by default. Use --json for the
stable machine contract, --plain for compact text, or --ascii for
Unicode-free output. Reports can be summarized, compared, or bundled for a
fixer handoff:
kova reports
kova report <run-id>
kova report compare <baseline-run-id> <current-run-id> --json
kova report bundle <run-id> --jsonThe JSON report uses the kova.report.v1 schema. Its fields and gate outcomes
are documented in the report schema.
run and matrix run are dry-run by default; real execution requires
--execute. Disposable environments are removed after a run. Durable user
environments are clone sources, never mutation targets, and exhaustive matrices
also require --allow-exhaustive.
Use --retain-on-failure to keep a failed disposable lab for inspection. The
agent workflow covers authentication, baselines,
existing-user tests, cleanup, and evidence handoff in depth.
Agents should plan and consume reports through JSON:
kova plan --json
kova matrix plan --profile smoke --target runtime:stable --json
kova report summarize <run-id> --jsonRepo-local kova-operator and ocm-operator skills live in .agents/skills/.
Load ocm-operator before executing scenarios that create environments, clone
state, build runtimes, upgrade installations, or inspect services.
- What Kova is explains the model and evidence pipeline.
- CLI reference lists commands, targets, profiles, and output controls.
- Agent usage is the operational workflow for real runs.
- Scenario hierarchy defines ownership across runtime paths.
- Diagnostics contract describes OpenClaw timeline evidence.
- Report schema documents reports, comparisons, bundles, and gates.
- Changelog records release changes.
npm ci
npm run check:full
npm run pack:releaseRelease archives include tracked documentation and images. Add new documentation to Git before packaging so it is included without copying untracked local notes.
Check the website with the same commands used in CI:
npm ci --prefix web
npm run check --prefix web
npm test --prefix web
npm run build --prefix webThe website matrix compares stable releases only. An empty or beta-only catalog shows "No stable releases yet." with zero releases and scenarios. The website tests exercise those catalogs through Astro as well as the populated matrix.
Install expect locally to include setup's hidden-input and cancellation PTY
checks in self-check; CI installs this prerequisite automatically.
CI runs the full check suite and release-install smoke test on Node.js 22, 24,
and 26 on Linux, and Node.js 24 on the Apple Silicon xcode-27 macOS runner. The website has a separate type-check,
test, and production-build job. .node-version pins the development, website,
hydration, and release-build runtime without changing the Node.js 22 CLI floor.
Rehearse the release build on current main without publishing:
gh workflow run release.yml --ref main -f version="$(node -p 'require("./package.json").version')" -f dry_run=trueManual runs require the current package version and a green exact-SHA main CI run. Publishing remains limited to validated tag pushes.
MIT.