Deployment | Kivo

Deployment modes

Enterprise Worker Deployment

Run the Kivo worker in your cloud, VPC, CI job, or controlled compute environment. Kivo receives metadata only.

Kivo API Deployment

Send approved review packets to Kivo hosted APIs. Kivo stores submitted packets, derived claims, reports, and verdicts.

Different credentials

Hosted API calls use scoped Kivo API keys. Worker events use one-run worker credentials returned by the private-worker create endpoint.

Comparison

Dimension	Enterprise Worker	Kivo API
`Best for`	Sensitive production traces, prompts, sources, embeddings, and screenshots.	Synthetic, sanitized, explicitly approved, or lower-sensitivity packets.
`Raw data`	Stays in your storage and compute.	Sent to Kivo hosted processing.
`Detailed reports`	Written to your storage.	Available through Kivo hosted app/API.
`Kivo stores`	Status, verdicts, counts, hashes, worker version, redacted categories, and storage pointers.	Submitted outputs, supplied sources, source spans, claims, reports, verdicts, and metadata.
`Primary endpoint`	/v1/private-worker/review-runs/{id}/events	/v1/review-runs
`Credential`	Run-scoped worker credential.	Project-scoped Kivo API key.

Enterprise Worker flow

First create a metadata-only private-worker run with a scoped Kivo API key. The response returns a one-run worker credential. Store that credential only in the worker runtime secret store.

Create private-worker run

curl -sS "$KIVO_API_BASE_URL/v1/private-worker/review-runs" \
  -H "Authorization: Bearer $KIVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "kivo_private_worker_review_run_create.v1",
    "customer_run_id": "cust_run_001",
    "workflow_id": "support_answer_review",
    "workflow_name": "Support answer review",
    "title": "Support answer check",
    "intended_use": "customer_facing",
    "strictness": "strict",
    "source_count": 4,
    "source_hashes": ["sha256:source_hash"],
    "output_hash": "sha256:output_hash",
    "worker_id": "worker_support_001",
    "worker_version": "kivo-private-worker.2026-05-09.v1",
    "policy_version": "standard-support-v1",
    "customer_storage_pointer": {
      "type": "customer_owned",
      "label": "Customer report store",
      "opaque_id": "reports/support_answer_review/cust_run_001"
    }
  }'

Then run the Kivo-provided worker from your approved input and output locations. The worker uses `--kivo-api-base-url`, `--review-run-id`, and `--worker-credential` to report metadata back to Kivo.

Worker command

kivo-worker run \
  --job-token local \
  --job-spec-file ./job-spec.json \
  --kivo-api-base-url "$KIVO_API_BASE_URL" \
  --review-run-id "$REVIEW_RUN_ID" \
  --worker-credential "$KIVO_WORKER_CREDENTIAL"

Metadata-only completion event

curl -sS "$KIVO_API_BASE_URL/v1/private-worker/review-runs/$REVIEW_RUN_ID/events" \
  -H "Authorization: Bearer $KIVO_WORKER_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "kivo_private_worker_review_run_event.v1",
    "event_id": "evt_cust_run_001_completed",
    "event_type": "completed",
    "review_run_id": "'"$REVIEW_RUN_ID"'",
    "customer_run_id": "cust_run_001",
    "worker_id": "worker_support_001",
    "worker_version": "kivo-private-worker.2026-05-09.v1",
    "sequence": 1,
    "status": "completed",
    "gate_verdict": "needs_review",
    "safe_use_status": "needs_review",
    "claim_count": 18,
    "unsupported_claim_count": 3,
    "source_count": 4,
    "source_hashes": ["sha256:source_hash"],
    "output_hash": "sha256:output_hash",
    "redacted_failure_categories": ["unsupported_policy_claim"],
    "artifact_summaries": [{
      "artifact_name": "claim_report",
      "artifact_type": "claim_report",
      "format": "json",
      "sha256": "sha256:claim_report_hash",
      "file_count": 1,
      "storage_label": "Customer report store"
    }]
  }'

Rejected raw fields

Do not send in worker events	Use instead
`ai_output`	output_hash and your report pointer
`prompt or system_prompt`	prompt_version or policy_version
`messages`	customer_run_id and workflow metadata
`source_text or source_spans`	source_count and source_hashes
`retrieved_context`	redacted failure categories
`embeddings, screenshots, uploads, tool traces`	opaque storage pointer