Creating, submitting and querying Runs#
A Run freezes its Scene, Policy Revision ID, Spec digest, Run TTL and the
caller-defined JSON context in changeSet. See core concepts and
Getting started for a complete example.
Create and query a Run#
A machine key needs runs:create to create a Run, runs:read to list or read it,
and submission-credential:rotate to replace its Submission Credential. Create a
Project key after administrator login.
Run the examples from the checkout or archive root with guardrailctl on PATH.
Set guardrail_credentials_dir to the private directory containing your
orchestrator-key.json, outside the checkout or extracted archive. If you used
the administrator guide in the same terminal, the variable is already set.
Otherwise, replace this placeholder with the private directory path:
guardrail_credentials_dir=/absolute/path/to/private/guardrail-credentials
New Run credentials stay in this directory. See Getting started for example
change-set.json and submission.json inputs.
Resource bindings select the Policy/Revision at creation; entirely unbound resources
use the Scene default active Revision. See bindings.
A trusted HTTP caller with runs:create-with-revision can explicitly select an immutable Revision
through policyRevisionRef; ordinary orchestrator keys cannot. The current CLI
has no explicit-Revision flag. Machine callers can inspect their effective scopes
through GET /runtime/v1alpha1/identity before enabling an integration.
guardrailctl run create --key-file "$guardrail_credentials_dir/orchestrator-key.json" \
--scene recovery --change-set ./change-set.json \
--operation-id create-123 \
--submission-credential-file "$guardrail_credentials_dir/run-credential.json"
guardrailctl run get --key-file "$guardrail_credentials_dir/orchestrator-key.json" run_EXAMPLE
guardrailctl run wait --key-file "$guardrail_credentials_dir/orchestrator-key.json" run_EXAMPLE
guardrailctl run list --key-file "$guardrail_credentials_dir/orchestrator-key.json" \
--scene recovery --status FINISHED --limit 20
Run lists contain bounded summaries with changeSetDigest, not the potentially
large changeSet. Use run get or GET /runtime/v1alpha1/runs/{runId} to read
the full immutable ChangeSet for one Run.
run wait polls GET /runtime/v1alpha1/runs/{runId} until the Run is terminal and
prints the final document. It exits 0 only for FINISHED; an EXPIRED Run exits
nonzero because no final Submission arrived before the deadline, and a timeout is
also a nonzero exit.
Transient transport, 5xx and 429 failures are retried until the deadline, while
authentication and other client errors fail immediately. Until the Run deadline is
known, connection retries are capped at 30 seconds. A 429 Retry-After value
longer than --interval is honored within the remaining wait. Waiting does not
replace the calling system's verification of the Decision, its validity and its
evidence.
Run retry and credential recovery#
POST /runtime/v1alpha1/runs returns a Run and a plaintext Submission Credential
only on first creation. The CLI writes the credential to a new private file.
An idempotent replay returns the Run without reissuing the credential.
Keep the same operation ID and input when retrying an uncertain creation or
Submission. Inspect the returned Run and any saved credential before retrying.
If the credential was not saved, rotate it while the Run is OPEN. Rotation
invalidates the old credential and does not extend the deadline:
guardrailctl run rotate-credential --key-file "$guardrail_credentials_dir/orchestrator-key.json" \
--submission-credential-file "$guardrail_credentials_dir/replacement-run-credential.json" run_EXAMPLE
The API path is POST /runtime/v1alpha1/runs/{runId}/submission-credential:rotate.
Only the matching Run credential can submit; the CLI never overwrites an existing
credential output file.
Rotation and Submission share the Run lock, and Submission rechecks its credential under that lock. A final Submission prevents rotation. After rotation succeeds, the old credential cannot create or replay a Submission; exact retries remain available with the current credential after the Run is terminal.
The server checks time after acquiring the Run lock, so waiting for a connection
or lock cannot extend the deadline. After the deadline, a new Submission or
rotation expires the Run and returns RUN_EXPIRED; exact retries of accepted
Submissions still return their original records.
Complete Snapshot Submissions#
Each Submission contains all Check verdicts and applicable structured evidence.
It is a complete Snapshot, including for an intermediate submission.
baseSubmissionNo must match the Run's latest number. The server verifies the
aggregate verdict: BLOCKED overrides UNKNOWN, and UNKNOWN overrides PASS.
The top-level summary field is required and may be "". Nonempty summaries
must contain non-whitespace text and stay within 2048 characters. Check summaries
and Evidence query/result summaries must contain non-whitespace text.
The JSON below is an illustrative shape. Use the actual observation time and findings, and include every Check required by your Run's frozen Spec.
{
"baseSubmissionNo": 0,
"finishRun": true,
"verdict": "PASS",
"summary": "Recovery checks passed",
"checks": [{
"checkId": "readiness",
"verdict": "PASS",
"summary": "Service is healthy",
"evidence": [{
"requirementId": "health",
"observedAt": "2026-10-26T00:00:00Z",
"querySummary": "Read current health metrics",
"resultSummary": "All replicas ready"
}]
}]
}
Save this as submission.json, then run:
guardrailctl run submit --submission-credential-file "$guardrail_credentials_dir/run-credential.json" \
--submission ./submission.json --operation-id submit-123 run_EXAMPLE
finishRun: false stores an intermediate Snapshot, increments
latestSubmissionNo, and leaves the Run OPEN. finishRun: true stores the
final Snapshot and atomically creates one Result and Decision, moving the Run to
FINISHED. An exact retry with the same idempotency key returns the original
Submission; a changed request conflicts.
Run state and decision validity#
| Constraint | Frozen source | Behavior |
|---|---|---|
deadlineAt |
Scene runTtlSeconds at Run creation |
Bounds the time for accepting a new Submission; intermediate Snapshots and rotation do not extend it |
decisionExpiresAt |
Selected Spec spec.validForSeconds |
Bounds the lifetime of a terminal Decision; expiry does not rewrite historical Result or Run state |
An unfinished Run observed at its deadline becomes EXPIRED with UNKNOWN / DENY.
A FINISHED Run stays FINISHED. Expiry and final Submission use the same Run
lock, so only one terminal outcome can win. An expired Run's Decision starts at
its logical deadline, even if the lazy expiry is persisted later.
PASS produces ALLOW; BLOCKED and UNKNOWN produce DENY. The calling
system must check the authoritative Run, decision validity, evaluation identity
and accepted evidence before acting. Execution Claims and ActionResults remain
planned; the server does not perform a deployment or independently attest to
submitted observations.
Read the immutable inputs and accepted evidence#
Project orchestrators can read a Run's Revision and Submission without Policy management permissions:
guardrailctl run revision --key-file "$guardrail_credentials_dir/orchestrator-key.json" "$RUN_ID"
guardrailctl run submission --key-file "$guardrail_credentials_dir/orchestrator-key.json" \
--submission-id "$SUBMISSION_ID" "$RUN_ID"
These map to GET /runtime/v1alpha1/runs/{runId}/policy-revision and
GET /runtime/v1alpha1/runs/{runId}/submissions/{submissionId}. The latter returns
Submission metadata plus its persisted snapshot. Both readers check scope and
Run membership; a Run Submission Credential cannot use them. For a finished Run,
use its finalSubmissionId as SUBMISSION_ID. Run metadata does not include the
full evidence Snapshot.
The management page shows the latest accepted Submission and its evidence by default.
An administrator can select earlier submissions from paginated metadata at
GET /api/v1alpha1/runs/{runId}/submissions?limit=20, then read one snapshot at
GET /api/v1alpha1/runs/{runId}/submissions/{submissionId}. Use nextBefore as
the next page's before parameter. Selecting history does not change the Run's
final result or decision. Project-key runtime readers remain unchanged.
Evidence limits#
Evidence is limited to 16 KiB per entry, 100 entries per Submission, and 1 MiB per request. Text limits are counted in Unicode code points. Credential-shaped content is rejected, including known credential fields in JSON summaries, nested objects, arrays and JSON-encoded strings. Duplicate JSON keys and excessive JSON structure are rejected too.
Screening preserves accepted text and its retry identity. Callers must still remove secrets before submission because free-form text screening is not a general data-loss prevention system. The management UI lists and inspects Runs without exposing credentials or accepting Submissions. See the OpenAPI contract for fields and error codes.
Use guardrailctl run create|list --business-id ID or the console Runs filter to find a business attempt. See the release-order correlation example for replay, credential and terminal-state handling.