Skip to content
wrt

writ witness

A witness records that it observed one signed record checkpoint. It receives the run ID, sequence, root hash, record signer key ID, and a fresh nonce. It does not receive entries, prompts, tool arguments, or results.

Run the witness under a different operator or on a different host when you need an independent observation.

1. Create the witness key

Section titled “1. Create the witness key”

Run this on the witness host:

Terminal window
writ witness keygen --out keys/witness.key.json

Keep the private key on the witness host. Give the public key to record producers and verifiers through a trusted channel.

2. Serve the endpoint

Section titled “2. Serve the endpoint”
Terminal window
writ witness serve \
  --name "Example Witness" \
  --key keys/witness.key.json \
  --addr 0.0.0.0:8322 \
  --tls-cert /etc/writ-witness/tls.crt \
  --tls-key /etc/writ-witness/tls.key

The endpoint is /v1/witness. A non-loopback listener requires TLS. A loopback listener can use HTTP for local operation.

Require a bearer token without putting it on the command line:

Terminal window
export WRIT_WITNESS_TOKEN='...'
writ witness serve \
  --name "Example Witness" \
  --key keys/witness.key.json \
  --token-env WRIT_WITNESS_TOKEN \
  --tls-cert /etc/writ-witness/tls.crt \
  --tls-key /etc/writ-witness/tls.key

The server reads the expected value from the environment for each request.

3. Attach a receipt

Section titled “3. Attach a receipt”

First export the signed record:

Terminal window
writ record export bug-fixer --out bug-fixer.writ-record.json

Then request and verify a witness receipt:

Terminal window
export WRIT_WITNESS_TOKEN='...'
writ record witness bug-fixer.writ-record.json \
  --url https://witness.example.com/v1/witness \
  --token-env WRIT_WITNESS_TOKEN \
  --witness-trust keys/witness.key.public.json \
  --out bug-fixer-witnessed.writ-record.json

The client verifies the record before it sends the checkpoint. It also verifies the returned signer, checkpoint fields, observation time, and nonce. A receipt from an earlier request does not match the fresh nonce.

4. Verify both signers

Section titled “4. Verify both signers”
Terminal window
writ record verify bug-fixer-witnessed.writ-record.json \
  --trust keys/project-record-signing-key.public.json \
  --witness-trust keys/witness.key.public.json

This proves that the trusted record signer signed the exported chain root and that the trusted witness signed its observation of that root. It does not prove that a reported tool effect occurred.