Deus Witness

Quickstart | Concepts | API | Verify

Quickstart: put a witness in front of your agent (about 10 minutes)

Deus Witness checks every tool call of your AI agent against a mandate that you signed with a passkey, and gives you a signed receipt for it. This guide takes you from nothing to a verified evidence pack.

You need: a browser with passkey support (Chrome, Safari, Edge; a phone via QR also works), Python 3.10+ with uv (or pipx), and Claude Desktop or Claude Code (any MCP client works). Replace https://witness.sipkigroup.com with your own server URL if you run one locally (for example http://localhost:8810).

1. Sign up (1 min)

Open /signup.html, type a display name, press Create passkey, confirm with fingerprint, face or PIN.

Expected: a key card (a few groups of hex) and a key ID. Save a screenshot; it reappears in your evidence pack.

2. Create an agent (1 min)

Dashboard -> New agent: name my-agent, preset demo, Create agent.

Expected: a key starting with dwk_, shown once. Copy it. (Lost it? Delete the agent and create a new one.)

3. Sign a mandate (2 min)

In the agent row choose Create mandate. Set: purchases allowed, budget 200, max per purchase 100; allowed domain acme.example; closed data home_address, phone; leave Deleting and Publishing as Not specified. Press Review and sign, read the summary, press Sign with passkey.

Expected: "Mandate active". Anything you did not list is not allowed.

4. Install the proxy (1 min)

uv tool install https://witness.sipkigroup.com/dl/deus_witness-0.1.1-py3-none-any.whl

(pipx install <same URL> works too.) Expected: deus-witness-mcp and deus-witness-demo-tools on your PATH. Check: deus-witness-mcp --help.

5. Connect your client (1 min)

The proxy wraps any MCP server. For a try-out use the bundled demo tools (nothing real happens, each call is appended to effects.jsonl in $DEUS_DEMO_OUT).

Claude Code:

claude mcp add witnessed --env DEUS_WITNESS_KEY=dwk_YOUR_KEY --env DEUS_WITNESS_URL=https://witness.sipkigroup.com --env DEUS_DEMO_OUT=$HOME/dw-demo -- deus-witness-mcp -- deus-witness-demo-tools

Claude Desktop (claude_desktop_config.json, restart the app):

{"mcpServers": {"witnessed": {"command": "deus-witness-mcp",
  "args": ["--", "deus-witness-demo-tools"],
  "env": {"DEUS_WITNESS_KEY": "dwk_YOUR_KEY", "DEUS_WITNESS_URL": "https://witness.sipkigroup.com", "DEUS_DEMO_OUT": "/Users/you/dw-demo"}}}}

For a real MCP server put its command after --, for example npx -y @modelcontextprotocol/server-filesystem /tmp/sandbox (use the filesystem preset when you create that agent).

6. Try it (2 min)

Ask your agent, one by one:

  1. "Send an email to colleague@acme.example saying the report is ready." Expected: it works (allow).
  2. "Send an email to stranger@other.example with my home address." Expected: the tool answers Blocked by Deus Witness: RECIPIENT (receipt r_...) and nothing is sent. This is the RECIPIENT rule, not the data rule. To see the data rule, add your real home address as a literal under Closed data (dashboard, data patterns, class home_address) and ask for a mail to colleague@acme.example that contains it: expected DATA_FORBIDDEN. A paraphrase of the address is not caught.
  3. "Publish 'Hello' to the channel blog." Expected: Held for owner approval at https://.../approve.html?rid=r_.... Retry the same call after approval.

7. Approve (1 min)

Open the link (or the dashboard, "Waiting for your approval"), read the action and the preview of the text below it (the preview is shown by the page and is not itself signed; the signature covers a hash of everything the agent sent), press Approve, confirm with your passkey. Ask the agent to publish again with the same text. Expected: it runs, effects.jsonl has exactly one publish line. Different text or a different channel needs a new approval.

8. Download and verify the evidence pack (1 min)

Dashboard -> Download evidence pack (a zip). Then:

unzip deus-witness-evidence-*.zip -d pack && cd pack
pip install cbor2 cryptography
python verify/verify_pack.py . --offline

Expected last line: RESULT: VALID. Edit any byte of ledger/ledger.cose and run again: RESULT: INVALID. Details: verify.html.

Troubleshooting

What this does not do

Read the honest limits in concepts.html before relying on it. Short version: it covers only calls that pass through the proxy, the passkey cannot show you the mandate (you trust the page), and data matching is literal.