Preview: Quoderat is in early access. This site shows the concept and direction — onboarding is manual for now.
Quoderat

Quickstart

Get from zero to your first Evidence Envelope in 5 minutes. This guide covers the minimum viable path.

What you'll have at the end

  • A functional Quoderat stack (Server + at least one Worker)
  • One completed run producing a JSON Evidence Envelope that contains:
    • • Execution steps: typed steps with recorded status/exit codes
    • • Hashed artifacts: content-addressed bytes (sha256 + content identity fields)
    • • Traceable observations: summaries that cite basis_artifact_ids
    • • Integrity seal: a finalized integrity.hash_chain

What this page does (and does not) claim

✓
Claim (mechanical)

It explains the minimum path to produce a finalized envelope and how to validate it.

✗
No claim (absolute)

  • • It does not claim the run is “correct”, “secure”, or that secrets “cannot leak”.
  • • It does not claim your public view is safe unless your allowlist is safe.

Prerequisites

  • 1
    A target Git repository — demo or local, to provide context
  • 2
    A container runtime — Docker or equivalent, or your existing deployment method
  • 3
    A place to store artifacts — local directory or object storage

Note: exact deployment topology is environment-specific; this guide focuses on the evidence contract.

Step 1 — Start the stack

Goal: bring up the Quoderat API and at least one Worker.

  • Verify the API is reachable (use your environment's health endpoint or equivalent).
  • Verify a Worker is available for execution (however your UI/ops surfaces that).

Outcome: you can submit a run and see it progress.

Step 2 — Define the context

Quoderat's receipts are only meaningful when the start state is explicit:

  • repo identity — URL or name
  • commit_sha — an immutable reference (or equivalent)
  • runner_type — e.g., local, ci, worker

Why commit_sha matters: It anchors the run to a specific starting point that can be rechecked later.

Step 3 — Issue an intent

Trigger a run with an intent that uses standard tooling:

  • • “run lint and tests”
  • • “build”
  • • “generate a report only”

Expected outcome:

  • You receive a run/job identifier.
  • You may observe progress via runtime signals (e.g., an event stream) until finalization.

Important: runtime signals are for monitoring; they are not the receipt.

Step 4 — Wait for finalization

The trust boundary is the finalized envelope, not the stream.

When finalized, you should be able to find:

integrity.canonicalization

set to rfc8785-jcs (or your configured canonicalization)

integrity.hash_chain

present (non-empty)

execution.steps

with typed kind and recorded outcomes

artifacts

with content identity (sha256 / content_uri / equivalent)

observations

that cite basis_artifact_ids

redactions[]

entries if masking rules were triggered

Step 5 — The trust moment

Core idea: You can validate the envelope and referenced artifacts without trusting live UI claims.

Validate in three checks:

1. Integrity (tamper-detection)

  • • Recompute hashes using RFC 8785 JCS canonicalization and SHA-256 (as configured).
  • • Walk the hash_chain and confirm it matches the data you received.

2. Artifact identity

  • • Download/resolve artifacts using location hints (best-effort pointers).
  • • Re-hash artifact bytes and compare to the sha256 recorded in the envelope.

3. Traceability of summaries

  • • For each observation (e.g., “tests passed”), verify it references basis_artifact_ids.
  • • Optionally re-derive the summary from the raw report artifact.

Sharing safely (Public vs Internal)

Deny-by-default:

  • Internal Envelope: full audit trail for operators/auditors.
  • Public View/Pack: a filtered export intended for sharing.

Mechanic:

  • • Only fields matching redaction_policy.public_allowlist_fields are exported.
  • • Artifacts can be classified internal/public.

Warning: A public view is only as safe as your allowlist. Quoderat guarantees the filtering mechanism, not the wisdom of chosen allowlist entries.

Troubleshooting

No artifacts recorded

Ensure your tools produce outputs that are captured as artifacts (logs/reports), and storage is configured.

Envelope not finalized / missing hash_chain

The run may have failed before finalization; inspect the final run state and worker logs.

Public view missing fields

Fields not on the public allowlist are stripped by design.

Next steps

  • First Job — full end-to-end lifecycle and how to read the envelope like an auditor
  • Concepts — identity, traceability, canonicalization, integrity
  • Policies — masking rules and public/internal visibility
  • Events (SSE) — runtime signals vs authoritative record
  • API — programmatic consumption and validation