Getting started

Proofroom gives your AI agent a verifiable evidence trail in four steps.

Recording evidence is fire-and-forget. Every Proofroom call is asynchronous and non-blocking — it never blocks your agent. If Proofroom is unreachable, your agent continues exactly as if we did not exist. Evidence is a side-channel and never sits in your agent's critical path. Delivery gaps (receipts expected vs recorded) are visible on the room health endpoint and public room page so missed evidence is detectable, not silent.

Default ingestion is Observe Mode (best-effort). Assurance Mode adds durable ack, local queue and retry when your runtime can hold a queue. See Observe and Assurance.

Descriptions are private by default. The public proof room renders only structural fields. Free-text titles and summaries appear publicly only if a human approves that specific text. Nothing an agent writes is published without human sign-off. The full record, including unpublished text, is hash-sealed at capture.

Materiality is classified server-side: your agent sends events, Proofroom decides which ones are material and mints receipts for them. Evidence levels are exactly three: self_reported, system_confirmed and operator_confirmed. See Evidence levels.

1. Register an Agent Passport

Sign in and register your agent: name, vendor stack, what it does. The passport identifies the agent; its powers live on use case passports.

You can also call the register_agent MCP tool (no API key required) or POST /api/register. You receive an API key, a room slug and a claim_url. A human must complete the claim gate before the room can be shared. Over MCP, pass that api_key into the next record_evidence_event on the same connection (see MCP integration); no connector reconfiguration.

2. Declare a Use Case Passport

Every artifact in Proofroom is scoped to one agent doing one job. Declare:

  • A scope summary in plain English
  • Allowed actions (what the agent may do in this use case)
  • Prohibited actions (what it must never do)
  • The oversight model (who checks what, when)
  • An evidence decay window (how fresh evidence must be for the room to stay current)
  • Optional: critical_actions (event types or tool names that should use require_ack; see below)

3. Create an API key and stream evidence

Create a key in Settings (shown once), or use the key returned at registration. Then send events as your agent works, via HTTP or MCP:

POST /api/events
Authorization: Bearer prf_live_...
Content-Type: application/json

{
  "use_case_slug": "your-use-case",
  "event_type": "output_generated",
  "event_summary": "Produced risk summary for DOC-1234",
  "actor": "my-agent",
  "metadata": { "action": "produce risk summaries" }
}

MCP: add https://your-deployment/api/mcp. After register_agent, pass the returned api_key on record_evidence_event (same connection). Or configure the connector bearer with a long-lived key. Full tool reference: MCP integration.

Events are appended to a hash chain. Material actions automatically receive Action Receipts (PRF-XXXXX) with declared evidence levels, a mandatory note on what is not verified, and (when signing is configured) an Ed25519 signature you can check offline. See Signed receipts.

Send proof, not payloads: keys that look like content (body, document, text, payload, token) are stripped at ingestion and reported back in the x-proofroom-redacted header.

Optional: require_ack for critical actions

Default recording stays fire-and-forget. For actions you designate as critical, pass "require_ack": true. The call returns only after a durable write, with ack: { event_id, seq, event_hash }. If that call fails, your agent decides whether to proceed. Proofroom never blocks anyone's agent itself. Using require_ack makes those actions dependent on our availability.

For actions that already happened outside declared scope, the default is observe-and-notify (notify-and-amend), not a gate. See Scope and drift.

4. Share your proof room

Every use case has a live proof room: status, coverage score, chain integrity, receipts, framework crosswalk and published Q&A. Share the tokened link, or generate an Evidence Pack for procurement teams.

Status decays if the agent stops reporting. Platform intake outages suspend the decay clock so our downtime is not shown as the agent going quiet; see Outage-safe decay and /status.

Chain heads are published daily to a public anchors repository so third parties can check them without trusting only us. Walkthrough: /verify and External anchoring.

The live link beats the static PDF.

What this trail does not show

This trail evidences what was recorded. It cannot evidence actions the agent did not report. Rooms list declared actions that have never produced a receipt as "declared but never recorded". Details: Absence of evidence.

Further reading