Tracekit is a signer that sits between an AI agent and its tools. Before each tool call runs, the signer checks it against your policy and allows it, denies it, or holds it for a person to approve. Every call and decision is written as a signed, hash-chained record that the agent can't edit. A run exports as one .tkb file that anyone can verify offline.

Why it exists

Agents now run shell commands, edit code, query databases and send messages on real systems. Most agent logs are written by the agent's own process, so whatever controls the agent can also edit them or skip them. When something goes wrong, you need a record you can trust. You also need to show it to someone else: a security team, an auditor, a customer. Tracekit keeps that record outside the agent's control, and lets anyone check it without trusting you.

What it does

Record

• Every tool call, its decision and its result, plus model calls and approvals, as signed records in one chain per run.
• A missed or lost event becomes a signed gap record. Gaps are never silent.

Decide

• Policy packs for coding agents, server agents, browser agents, SQL, HTTP, cloud CLIs, and payments and messaging (policy reference).
• Each call is allowed, denied, or held until a person answers (ask).

Approve

• A held call runs only after an approver says yes. The approval is bound to the exact arguments and used once.
• Approvers answer from the command line, from a web page with OIDC sign-in and passkeys, or from Slack (approvals).
• A reviewer agent may answer routine approvals inside bounds the policy sets, with budgets and a veto delay; people answer everything else (agent approvers).

Contain (1.2, experimental)

• The policy names risky sequences of calls and limits on them. When one trips, the signer opens a signed incident and can hold or quarantine the run; new runs of the same owner and principal inherit that for a cooldown (incidents).
• Tool calls can run with credentials the agent never holds, through the signer's tool executor or MCP gateway.
• An egress observer outside the agent records the network effects it sees and flags ones no recorded call explains. Each finished run reports, per action class, whether it was enforced, observed, only reported, or not covered.

Prove

• tracekit verify checks a bundle offline against keys you pinned.
• Witnesses cosign checkpoints of the log, and a monitor watches it from outside (witnesses, monitor).
• Each report states an assurance level: dev, local, witnessed or witnessed+monitored (reading a verify report).

Watch

• tracekit view shows runs with their verdicts, blocked and held calls, approvals, gaps, a replay of each run, and a run review (viewer).

Explain (1.2, experimental)

• Where each argument came from: the signer tracks values that entered a run through untrusted content (a fetched page, an email, a ticket) and can hold a call whose recipient, payee or host came only from there (provenance).
• Which input caused an action: tracekit why replays a run with each suspect input removed, tools served from the recording, and reports the cause with a confidence interval; results on signed runs are signed findings the verifier rechecks (tracekit why).

Integrate

• Coding agents through their hooks: Claude Code, Codex CLI, Cursor, Gemini CLI (coding agents).
• Python and TypeScript SDKs, with integrations for LangChain and LangGraph, the OpenAI Agents SDK, the Claude Agent SDK, MCP clients, Browser Use and CrewAI (Python) and the Vercel AI SDK (TypeScript) (quickstarts).
• OpenTelemetry traces imported as evidence (OpenTelemetry).
• An LLM gateway for OpenAI-compatible APIs that records model calls outside the agent's process (gateway).

How it works

  agent ──► client or hook ──────► signer ─────────────► witnesses
            (SDK, adapter,         - policy: allow,       cosign each
             coding-agent hook)      deny or ask          checkpoint
            holds a run token,     - keys: signs every
            never a key              record
                                   - log: hash chain,
                                     Merkle checkpoints
                                          │
                                          ▼
                                    run.tkb bundle ──► tracekit verify
                                                       (offline, with the keys
                                                        and witnesses you pinned)

1. The agent's client asks the signer to decide each tool call before it runs.
2. The signer decides with its own policy, signs the decision, and adds it to the log.
3. After the call, the client reports the result, and the signer records that too.
4. The signer signs checkpoints of the log. Witnesses cosign them.
5. A run is exported as a bundle. Anyone can verify it offline.

The trust model:

• The agent never holds a signing key and never assigns sequence numbers.
• Nothing the agent reports about itself is trusted: not its isolation, its fail mode, gaps, or who approved a call. The signer measures or configures these itself.
• Who can rewrite the log decides what a bundle is worth. A dev signer runs as your own user, so an agent that runs commands as you can rewrite it. A signer under a separate OS user, in a container sidecar, or on a central host is out of the agent's reach.
• The operator who runs the signer could still rewrite its log with its own key. An independent witness and a monitor make that visible.

The full model: architecture, laptop and server threat models.

Quickstart (under two minutes)

Three steps, with the agent you already have (OpenAI Agents SDK, LangGraph / LangChain, Claude Agent SDK, an MCP client, or plain OpenAI / Anthropic / Google Gen AI calls):

pip install tracekit-ai

import tracekit; tracekit.instrument()     # the first line of your agent; then run it as usual

tracekit last                               # Integrity: VERIFIED. / Assurance: dev; ...

tracekit.instrument() starts a dev signer in the background (or reuses the running one) and gates and records every tool and model call of the frameworks it finds. tracekit last exports the most recent finished run, pins the dev signer's key, verifies the bundle and says where it is. Then tracekit view --dev browses every run: verdicts, denials, approvals, replay. A call the policy holds for a person (ask) pauses the run or waits, depending on the framework: how each integration waits.

Per framework, with a 10-line example each: OpenAI Agents SDK, LangChain / LangGraph, Claude Agent SDK, MCP client, a custom agent. The v2 quickstart explains each step and what dev assurance means; limits lists what this path doesn't cover.

See it

tracekit view --dev opens the one viewer on your runs: each run verified, every call with its decision, and (with why logs) why a call happened, down to clicking any node of the run's graph. A store opened without why logs gets a graph of each signed run's calls and their decisions.

A screenshot tour of every panel: viewer tour. Every step end to end, recorded on a clean install with its real output and screenshots: walkthrough.

No agent at hand? Each demo runs in a temp dir and needs no API key. --server shows calls allowed, denied and approved, a witness cosignature, and a tampered copy failing verification. --why shows a held email whose cause is found by replay and cited by its signed record. init --dev --v2 wires Claude Code's hooks to a dev signer:

tracekit demo --server                # exit 0
tracekit demo --why                   # exit 0
tracekit init --dev --v2

From a checkout, python examples/v2/langchain/agent.py --scripted runs a LangGraph agent with a mock model.

Or, from a checkout, check the shipped sample bundles (v1) with the verifier alone (pip install --no-deps tracekit-ai is enough):

tracekit verify docs/sample/demo-run.tkb --key docs/sample/signer.pub            # exit 0
tracekit verify docs/sample/demo-run-tampered.tkb --key docs/sample/signer.pub   # exit 1

What you need

• Python 3.9 to 3.13, and pip install tracekit-ai. The framework integrations need Python 3.10 or newer. For the TypeScript SDK, Node 18 or newer and the package file from the GitHub release: npm install https://github.com/Cygnux-Labs/Tracekit/releases/download/v1.2.0/cygnux-tracekit-1.2.0.tgz. It isn't on npm yet (TypeScript SDK).
• An OS. Dev mode runs on macOS, Linux and Windows. A signer under its own OS user runs on Linux (macOS is experimental). Containers and Kubernetes run on Linux (platforms).
• To try it: nothing more. Dev mode starts a signer as your own user.
• For protection against the agent: a signer the agent can't reach. That is a separate OS user, a container sidecar, or a central signer (deployment guide).
• For protection against the operator: a witness the operator doesn't control, and a monitor.
• For approvals by people: approvers listed in the signer's config. They answer from the command line, or through an OIDC identity provider (web page, passkeys) or Slack (identity).

Be careful with

• Dev mode protects nothing against an agent that runs as you. It can read the key, stop the signer and re-sign the log; dev bundles say isolation: same-user (FAQ).
• A verified bundle proves the record is intact. It does not prove intent, that a reported tool result is true, or that every action was captured (FAQ).
• Actions outside the capture path leave no record, such as a subprocess a hook never sees or code that skips the adapter (adapters).
• Policy rules match text. A determined agent can reword a command so no rule matches. Rules are tripwires; the protection is the signer's isolation (policy reference).
• Rules match tool names. A shell tool named run_command is not covered by the shell rules until you map it (adapters).
• Fail-open tool classes run while the signer is down, unrecorded; the signer then writes a signed gap for them. Every class fails closed by default (FAQ).
• The agent's own claims are never trusted. Isolation, fail modes and approvers come from the signer's config, so set them there (approvals).
• Without an independent witness, the operator can rewrite the log unseen. A system-mode signer with no witness still verifies as Assurance: dev (deployment).
• Commitments hide content, not metadata. Timing, sizes and counts still show, and witnesses learn when checkpoints happen (privacy).
• The viewer's verdicts are operator-side. For evidence, verify the bundle yourself with keys you pinned (viewer).

Every limit: docs/limits.md

Deployment modes

The agent's code is the same in every mode; TRACEKIT_SIGNER points it at the signer.

Each mode end to end, with its commands, its tracekit doctor check and the assurance its bundles reach: deployment guide. Moving from the v1 signer or from a laptop to a server: migration.

The evidence format

For anyone evaluating the format itself, or writing another verifier:

• Specified. Evidence format v2 aims to be precise enough to write an independent verifier. Normative test vectors pin canonical JSON, record signatures and checkpoints.
• Built on standards. Canonical JSON is JCS (RFC 8785). Records are signed with Ed25519. Each log is an RFC 6962 Merkle tree. Checkpoints are C2SP signed notes, and witnesses cosign them per C2SP tlog-cosignature.
• Self-contained. A bundle is a zip of records, inclusion proofs, checkpoints and the policy snapshots that decided the calls. It holds no verification code. The verifier checks it offline against a trust file you pinned: log keys, witnesses and quorum, and optionally a monitor.
• Old bundles keep verifying. Formats only grow, and each format's verifier is frozen. v1 bundles go to the v1 verifier, which needs only the Python standard library.
• Forward-safe. A bundle names the minimum verifier version it needs. An older verifier reports it UNVERIFIABLE (needs tracekit >= x), never FAILED.

Use in CI

Verify a v1 bundle in a GitHub Actions workflow:

- uses: Cygnux-Labs/Tracekit@main
  with:
    bundle: run.tkb
    key: keys/signer.pub        # pin the signer; or witness: git:/path/to/clone

require-anchor defaults to true, so an unanchored bundle fails the step; set require-anchor: "false" to only report it.

Docs

• Seeing it work: a walkthrough of every step, recorded on a clean install with screenshots; recorded demos of each main use case, offline, with their bundles and verify reports
• The tour: a terminal video of every demo running (3 min 44 s)
• What's stable and what's experimental: support
• How it fits together: architecture, evidence format v2
• Running it: deployment, compose, container, Kubernetes, doctor, witnesses, monitor, viewer, observability, privacy, remote ingest, record-key issuer
• Deciding calls: policy reference, approvals, LLM gateway, tool executor, MCP gateway, egress observer, incidents, webhooks, OpenTelemetry
• Checking evidence: reading a verify report, auditor guide, evaluation, technical report, FAQ and limits, known limits and trade-offs, security checklist, case study: two open-source agents
• Asking why an action happened: tracekit why, its architecture
• Releasing: the procedure, launch checklist
• The v1 laptop signer (tracekitd, tracekit init --dev, tracekit demo, tracekit view --ledger) and its bundles keep working: coding agents, signing, findings, v1 adapters and integrations, platforms

Status

This is 1.2.0. 1.0 was the first stable release, and 1.x is the supported line (SECURITY.md). What changed in each release: CHANGELOG.md.

• Stable: evidence format v2 and its verifier. 1.x verifiers verify every 1.0 bundle. v1 bundles and the v1 verifier are unchanged.
• Versioned: the signer RPC (version 16; a 1.2 signer also serves version 15 clients). A client newer than its signer is refused, so upgrade the signer first (changelog).
• Stable core: the v2 signer (dev mode and Linux system mode, file storage), the Python SDK with tracekit.instrument() and its OpenAI Agents, LangChain / LangGraph, Claude Agent SDK and MCP integrations, the Claude Code hooks (v2), policy v2 with its packs, bundle export, the Python and TypeScript verifiers, tracekit view and tracekit doctor.
• Experimental: everything else. It works and is tested, but may change and gets less hardening; experimental commands and servers say so when they start (what's stable). The v1 OTLP receiver, ingest gateway and model proxy also need --experimental.
• Not yet done: an external review of the threat models, and some release checks that wait on the owner (launch checklist).

Contributing and security

CONTRIBUTING.md: make install, then make check. Report vulnerabilities privately as described in SECURITY.md.

Licence

MIT, Copyright Cygnux Labs. See LICENSE.