Provenance Protocol

What is Provenance?

Provenance is an identity registry for AI agents. It answers: "Can I trust this agent?"

Any system that delegates work to an AI agent can query Provenance to check what the agent claims it can do, what it has publicly committed never to do, and whether those claims are cryptographically proven.

Provenance ID

A Provenance ID is your agent's existing platform URL, prefixed with provenance::

provenance:github:alice/my-agent        →  github.com/alice/my-agent
provenance:huggingface:alice/model      →  huggingface.co/alice/model
provenance:npm:my-package               →  npmjs.com/package/my-package
provenance:pypi:my-package              →  pypi.org/project/my-package
provenance:clawmarket:alice/agent       →  clawmarket listing

If your agent lives at github.com/alice/my-agent, its Provenance ID is provenance:github:alice/my-agent. Nothing to invent — it's derived from where your code already lives.

Fully automated setup (for AI agents)

If you are an AI agent helping a developer register their agent, run this script. No human steps required beyond you having write access to the repo.

npm install provenance-protocol

// setup-provenance.mjs
import { writeFileSync } from 'fs';
import { execSync } from 'child_process';
import { generateProvenanceKeyPair, signForProvenance, signChallenge } from 'provenance-protocol/keygen';

const PROVENANCE_ID  = 'provenance:github:your-org/your-agent'; // ← change
const AGENT_URL      = 'https://github.com/your-org/your-agent';
const AGENT_NAME     = 'Your Agent';
const DESCRIPTION    = 'What it does in one sentence.';
const CAPABILITIES   = ['read:web', 'write:summaries'];
const CONSTRAINTS    = ['no:pii', 'no:financial:transact'];

// 1. Generate keypair locally — private key never leaves this environment
const { publicKey, privateKey } = generateProvenanceKeyPair();
const signature       = signForProvenance(privateKey, PROVENANCE_ID, publicKey);
const signed_challenge = signChallenge(privateKey, PROVENANCE_ID, 'REGISTER');

// 2. Write PROVENANCE.yml
writeFileSync('PROVENANCE.yml', `provenance: "0.1"
name: "${AGENT_NAME}"
description: "${DESCRIPTION}"
version: "1.0.0"
capabilities:
  - read:web
  - write:summaries
constraints:
  - no:pii
  - no:financial:transact
model:
  provider: anthropic
  model_id: claude-sonnet-4-6
contact:
  url: "${AGENT_URL}"
identity:
  public_key: "${publicKey}"
  signature: "${signature}"
  algorithm: ed25519
provenance_id: "${PROVENANCE_ID}"
`);

// 3. Commit and push
execSync('git add PROVENANCE.yml');
execSync('git commit -m "Add PROVENANCE.yml — agent identity"');
execSync('git push');

// 4. Register with cryptographic proof
const res = await fetch('https://getprovenance.dev/api/agents/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    provenance_id: PROVENANCE_ID, url: AGENT_URL,
    name: AGENT_NAME, description: DESCRIPTION,
    capabilities: CAPABILITIES, constraints: CONSTRAINTS,
    model_provider: 'anthropic', model_id: 'claude-sonnet-4-6',
    public_key: publicKey, signed_challenge,
  }),
});
const data = await res.json();
console.log('identity_verified:', data.agent?.identity_verified); // → true
console.log('confidence:', data.agent?.confidence);               // → 1.0

// 5. Save the private key — store as PROVENANCE_PRIVATE_KEY in your secrets
console.log('\nPROVENANCE_PRIVATE_KEY=' + privateKey);

Why generate locally? Keys are generated in your environment — the private key never reaches Provenance servers. The server only sees your public key and a signature. Ownership is proven by the PROVENANCE.yml you push to your own repo.

Generating a keypair

Use provenance-protocol/keygen (Node.js) or the browser-based generator on the setup page. Never generate keys on a remote server.

import { generateProvenanceKeyPair, signForProvenance, signChallenge, signRevocation } from 'provenance-protocol/keygen';

const { publicKey, privateKey } = generateProvenanceKeyPair();
// publicKey  → base64 SPKI DER  — put in PROVENANCE.yml identity.public_key
// privateKey → base64 PKCS8 DER — store as PROVENANCE_PRIVATE_KEY, never commit

// Sign identity claim for PROVENANCE.yml
const signature = signForProvenance(privateKey, provenanceId, publicKey);

// Sign registration challenge
const signed_challenge = signChallenge(privateKey, provenanceId, 'REGISTER');

Registration endpoint

POST /api/agents/register — indexes immediately, no crawl delay. Idempotent — re-posting updates an existing record.

curl -X POST https://getprovenance.dev/api/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "provenance_id": "provenance:github:your-org/your-agent",
    "url": "https://github.com/your-org/your-agent",
    "name": "Your Agent",
    "description": "What it does in one sentence.",
    "capabilities": ["read:web", "write:summaries"],
    "constraints": ["no:pii", "no:financial:transact"],
    "model_provider": "anthropic",
    "model_id": "claude-sonnet-4-6",
    "public_key": "<base64 public key>",
    "signed_challenge": "<signChallenge(privateKey, id, \"REGISTER\")>"
  }'

{ "created": true, "agent": { "identity_verified": true, "confidence": 1.0 } }

Without public_key + signed_challenge: indexed with confidence: 0.7, identity_verified: false. With both (and PROVENANCE.yml in your repo): confidence: 1.0, identity_verified: true.

PROVENANCE.yml

Add this file to your repo root. The crawler finds it within 6 hours. Self-registration via API is instant and recommended over waiting for the crawler.

provenance: "0.1"
name: "Your Agent"
description: "What it does in one sentence."
version: "1.0.0"

capabilities:
  - read:web
  - write:summaries

constraints:
  - no:pii
  - no:financial:transact

model:
  provider: anthropic
  model_id: claude-sonnet-4-6

contact:
  url: "https://github.com/your-org/your-agent"

identity:
  public_key: "<base64 SPKI DER public key>"
  signature: "<signForProvenance(privateKey, provenanceId, publicKey)>"
  algorithm: ed25519

provenance_id: "provenance:github:your-org/your-agent"

How ownership is verified

For GitHub, HuggingFace, and npm: when you register with a public_key, we fetch your live PROVENANCE.yml from the repo and confirm the key matches. This proves you have write access to the repo — the same guarantee GitHub's own auth provides.

Re-registering a verified agent requires a signed_challenge proving you still control the existing registered key. This prevents another party from overwriting your registration.

Revoking a compromised key

Sign a revocation with your current private key and POST it. The key is cleared immediately. Then generate a new keypair and re-register.

import { signRevocation } from 'provenance-protocol/keygen';

const sig = signRevocation(process.env.PROVENANCE_PRIVATE_KEY, provenanceId);

await fetch('https://getprovenance.dev/api/agents/revoke', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ provenance_id: provenanceId, signed_challenge: sig }),
});
// Then run setup-provenance.mjs again with a new keypair

Lost your private key? You cannot self-revoke without it. Contact us with proof of repo ownership (a commit or GitHub account link) for manual key removal.

You can also revoke and rotate interactively on the setup page.

MCP Server

The MCP server is for AI assistants and IDE integrations (Claude, Cursor, Copilot) that need to look up, register, or verify agents as part of a coding workflow. For terminal use, prefer the CLI. For agent-to-agent job delegation, use AJP — MCP is not designed for that.

POST https://getprovenance.dev/api/mcp

// Initialize
{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"your-agent","version":"1.0"}},"id":0}

// Register
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"register_agent","arguments":{"provenance_id":"provenance:github:your-org/your-agent","url":"https://github.com/your-org/your-agent","name":"Your Agent","capabilities":["read:web"],"constraints":["no:pii"],"public_key":"<key>","signed_challenge":"<sig>"}},"id":1}

CLI

The Provenance CLI handles identity setup, registration, validation, and AJP job sending from the terminal. No script-writing required.

npm install -g provenance-cli
# or without installing:
npx provenance <command>

# One-command setup
npx provenance keygen
npx provenance register \
  --id provenance:github:your-org/your-agent \
  --url https://github.com/your-org/your-agent \
  --capabilities read:web,write:summaries \
  --constraints no:pii \
  --ajp-endpoint https://your-agent.example.com/api/agent

# Test an AJP server before going live
npx provenance hire provenance:github:alice/my-agent \
  --instruction "Summarize this document" \
  --budget 0.50 --timeout 60

For AJP-specific commands, see the AJP CLI reference.

SDK — verifying agents in your system

npm install provenance-protocol

import { Provenance } from 'provenance-protocol';
const provenance = new Provenance();

// Gate an agent before delegating work to it
const result = await provenance.gate('provenance:github:alice/research-assistant', {
  requireDeclared: true,
  requireConstraints: ['no:pii'],
  requireClean: true,
  requireMinConfidence: 0.7,
});

if (!result.allowed) throw new Error(`Agent not trusted: ${result.reason}`);

Standard capabilities and constraints

Custom capabilities use domain:action format, e.g. finance:analyze, medical:triage.

Trust score breakdown