Local developer quickstart (≤5 minutes)

If you are integrating with a hosted GovAI backend, start here instead (canonical):

• customer-onboarding-10min.md

Goal: create an API key, send your first evidence event, run a compliance check, and interpret the result.

This guide uses the core v1 HTTP API (api/govai-http-v1.openapi.yaml) and the shipped govai CLI (python/aigov_py/cli.py).

curl -sS -X POST "$GOVAI_AUDIT_BASE_URL/evidence" \
  -H "Authorization: Bearer $GOVAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"evaluation_reported","run_id":"demo-run","payload":{"passed":true}}'

{ "status": "recorded", "event_id": "…" }

Prereqs#

• Rust toolchain
• Python ≥ 3.10
• PostgreSQL reachable via DATABASE_URL

0) Install the CLI (local editable)#

cd python
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cd ..
govai --version

1) Create an API key (shared secret)#

GovAI audit API keys are configured on the audit service via GOVAI_API_KEYS (comma-separated). When set, audit routes require Authorization: Bearer <secret>.

Note (local/dev vs hosted): This quickstart uses GOVAI_API_KEYS for simple local/dev setups. Hosted / staging / production deployments MUST define GOVAI_API_KEYS_JSON so each API key is mapped to a tenant id and ledger isolation is enforced correctly. Dev mode without API keys is not suitable for pilots: hosted pilots must run with real key → tenant mapping.

• Ledger tenant isolation is derived from the API key → tenant mapping (not from request headers).
• X-GovAI-Project is optional metadata (usage/billing label) and does not isolate ledger tenant.

Generate a local key:

export GOVAI_API_KEY="$(python3 - <<'PY'
import secrets
print(secrets.token_urlsafe(32))
PY
)"

2) Start the audit service with that key#

export DATABASE_URL='postgresql://USER:PASSWORD@127.0.0.1:5432/DBNAME'
export GOVAI_API_KEYS="$GOVAI_API_KEY"

make audit_bg
curl -sS http://127.0.0.1:8088/status

3) Send your first evidence event (HTTP)#

Pick a run_id (GOVAI_RUN_ID), then append one data_registered event.

4) Run a compliance check (HTTP + CLI)#

[!summary] After one evidence event, compliance-summary should return BLOCKED until the full promotion sequence is recorded.

At this point (only 1 event), the expected verdict is BLOCKED.

• The server only returns VALID when evaluation passed, risk reviewed (approve), human approved (approve), and promotion executed for the run.
• With only data_registered, those prerequisites are missing, so the run is intentionally blocked.

Get a full end-to-end VALID run (CLI)#

The fastest path to a complete, policy-satisfying sequence is the built-in scripted demo flow.

export GOVAI_AUDIT_BASE_URL="http://127.0.0.1:8088"
export GOVAI_API_KEY="$GOVAI_API_KEY"

govai run demo

Expected stdout:

VALID

Note: govai run demo generates its own run_id internally. It is a separate path from the API-only steps above (which use your $GOVAI_RUN_ID).

Optional: minimal VALID evidence sequence (API-only)#

If you want to reach VALID using only the HTTP API, append the remaining required evidence for the same $GOVAI_RUN_ID (in this order):

1. model_trained
2. evaluation_reported (with "passed": true)
3. risk_recorded
4. risk_mitigated
5. risk_reviewed (with "decision": "approve")
6. human_approved (with "scope":"model_promoted" and "decision":"approve")
7. model_promoted

Copy/paste (uses deterministic IDs derived from $GOVAI_RUN_ID):

export MODEL_VERSION_ID="mv_$GOVAI_RUN_ID"
export ASSESSMENT_ID="asmt_$GOVAI_RUN_ID"
export RISK_ID="risk_$GOVAI_RUN_ID"
export ARTIFACT_PATH="python/artifacts/model_${GOVAI_RUN_ID}.joblib"

post_ev () {
  local event_type="$1"
  python3 - "$event_type" <<'PY' | curl -sS http://127.0.0.1:8088/evidence \
    -H "content-type: application/json" \
    -H "authorization: Bearer $GOVAI_API_KEY" \
    -d @-
import json, os, sys

Now the expected verdict is VALID:

curl -sS "http://127.0.0.1:8088/compliance-summary?run_id=$GOVAI_RUN_ID" \
  -H "authorization: Bearer $GOVAI_API_KEY"

govai check --audit-base-url "http://127.0.0.1:8088" --api-key "$GOVAI_API_KEY" --run-id "$GOVAI_RUN_ID"
echo $?

Expected:

• GET /compliance-summary: "verdict":"VALID"
• govai check: stdout VALID, exit code 0

5) Interpret the result#

GET /compliance-summary returns:

• verdict: one of VALID, INVALID, BLOCKED
• current_state: the projected state derived from the evidence log
• policy_version and deployment environment metadata

Minimal, machine-friendly check (exit code 0 only if VALID):

govai check --audit-base-url "http://127.0.0.1:8088" --api-key "$GOVAI_API_KEY" --run-id "$GOVAI_RUN_ID"

6) Export the run (machine-readable JSON)#

Use the dedicated export endpoint to fetch a stable JSON document that includes:

• decision extracts (evaluation / approval / promotion)
• hashes (canonical bundle SHA-256 + append-only chain hashes)

CLI:

govai export-run \
  --audit-base-url "http://127.0.0.1:8088" \
  --api-key "$GOVAI_API_KEY" \
  --run-id "$GOVAI_RUN_ID"

HTTP:

curl -sS "http://127.0.0.1:8088/api/export/$GOVAI_RUN_ID" \
  -H "authorization: Bearer $GOVAI_API_KEY"

Appendix: single-line compliance summary (CLI)#

govai compliance-summary \
  --audit-base-url "http://127.0.0.1:8088" \
  --api-key "$GOVAI_API_KEY" \
  --run-id "$GOVAI_RUN_ID" \
  --compact-json