Ruflo v3.32.26 introduces a controlled self-improvement loop for retrieval. It can generate candidate settings, test them against held-out tasks and safety checks, and give you a signed record of the result—all while leaving your active configuration untouched.
You stay in control of the final step. Ruflo will not serve a candidate merely because it scored better. You review the evidence and explicitly promote it.
1. Evaluate candidates without changing the live policy
2. Inspect the signed receipt and resource results
3. Promote an accepted candidate when you are ready
This guide takes you through that workflow using the safe local proposer. It is for developers and operators who want measurable retrieval tuning with a clear audit trail, without enabling unattended optimization.
Important: evaluation is non-serving by design. Promotion requires an accepted receipt, a trusted public key, and an explicit
--confirm.
npm install --global ruflo@3.32.26
ruflo --versionYou can also run without a global install by replacing ruflo below with npx ruflo@3.32.26.
Run from the project you want to evaluate:
ruflo metaharness flywheel status --project-root .The response includes the active champion, serving epoch, ledger head, and ledger verification result.
Keep the private key outside your source repository:
mkdir -p ~/.config/ruflo/keys
chmod 700 ~/.config/ruflo/keys
openssl genpkey -algorithm Ed25519 -out ~/.config/ruflo/keys/flywheel-private.pem
openssl pkey -in ~/.config/ruflo/keys/flywheel-private.pem \
-pubout -out ~/.config/ruflo/keys/flywheel-public.pem
chmod 600 ~/.config/ruflo/keys/flywheel-private.pemDo not commit the private key.
ruflo metaharness flywheel run \
--project-root . \
--proposer local \
--sample 40 \
--private-key ~/.config/ruflo/keys/flywheel-private.pem \
--public-key ~/.config/ruflo/keys/flywheel-public.pemThis evaluates bounded retrieval-policy candidates against Ruflo's train, held-out, frozen-anchor, drift, replay, receipt-coverage, and canary gates. It does not activate the candidate.
An accepted result must satisfy the configured gate, including the default statistical requirements:
- at least 2% relative lift;
- at least 95% paired-bootstrap probability of improvement;
- a positive lower bound on the 95% bootstrap interval;
- no frozen-anchor regression.
ruflo metaharness flywheel receipts --project-root .
ruflo metaharness flywheel history --project-root .Before promotion, confirm that the receipt:
- says
accepted; - is signed by the key you trust;
- references the expected baseline and ledger head;
- records acceptable resource observations;
- has the expected effective proposer and no unexpected substitution.
Copy the accepted receiptId from the receipt list:
ruflo metaharness flywheel promote <receipt-id> \
--project-root . \
--public-key ~/.config/ruflo/keys/flywheel-public.pem \
--confirmPromotion fails closed if the receipt is stale, altered, unsigned by the trusted key, already consumed, or no longer matches the active policy state. Concurrent attempts are idempotent: only one promotion can commit.
Verify the result:
ruflo metaharness flywheel status --project-root .
ruflo metaharness flywheel history --project-root .The standalone Metaharness surfaces are available:
ruflo metaharness evolve --help
ruflo metaharness bench --helpDarwin is a candidate proposer, never the promotion authority. In the flywheel command, explicit Darwin mode fails closed unless a Darwin adapter has been configured. auto may fall back to local evaluation, but a substituted run is evaluation-only by default.
- The new flywheel commands never use the legacy implicit-apply path.
- Legacy callers can temporarily opt into old mutation behavior with
RUFLO_FLYWHEEL_LEGACY_APPLY=1; new deployments should not enable it. - Tool-policy evolution, model-policy evolution, and unattended promotion are not activated in v3.32.26.
- Private signing keys should use an external secret or key-management provider in production.
- Removing the optional Darwin/Flywheel dependencies leaves the local flywheel operational.