CAIN-42 · See what your agents do

CAIN Trace

A tamper-evident record of every step an agent took, in order.

Last reviewed 2026-10-01

Live Core platform · infrastructure

What it is

Immutable execution trace and audit trail.

Where it fits

Part of See what your agents do: Every action, every decision, replayed and searchable. Every CAIN-42 product runs behind the same rule: an AI agent's action is checked before it runs (identity, authority, policy, risk), decided as allow, hold for a human, or block, and recorded as signed evidence. Unknown or error never becomes allow.

Use it

Open it https://cainstudio.online/trace
Documentation https://cainstudio.online/docs/trace
API endpoint: https://cainstudio.online/fabric/traces/ — needs your API key (get a free key)

Recorded status: PRODUCTION. "Live" on this page means its link answered when the catalog was last checked (2026-10-01T18:22 UTC).

Live now

Checked from your browser when this page opened, not from a cached list.

Fire a real decision

Send an action through the live CAIN-42 pipeline from this page, with no account, and watch every stage decide. This is the same pipeline every product here sits behind; it runs for a throwaway demo tenant and is rate limited.

For AI engineers

Every product sits behind one decision path: your agent proposes an action with the exact arguments, CAIN runs it through identity, authority, policy, risk, trust and quorum consensus, and answers ALLOW, REQUIRE_APPROVAL or DENY with an Ed25519-signed record. A timeout, outage or unknown verdict never becomes ALLOW. A brand-new agent has no trust history, so its first actions usually come back REQUIRE_APPROVAL.

Python (zero dependencies)

pip install https://cainstudio.online/cainstudio-0.3.0-py3-none-any.whl
export CAIN_API_KEY=...   # free key: https://cainstudio.online/signup

import cainstudio

@cainstudio.guard()
def transfer(amount_usd: float, to: str) -> str:
    ...  # runs only if CAIN allows this call, with these arguments

try:
    transfer(5000, "acme")
except cainstudio.ApprovalRequired as e:
    print("held for a human:", e.approval_id)
except cainstudio.ActionBlocked as e:
    print("refused:", e.decision.reasons)
except cainstudio.CainUnavailable:
    print("CAIN unreachable: not run")   # fail-closed

See a real decision with no account

cainstudio try          # live pipeline, stage by stage
cainstudio try --list   # the other attack scenarios

MCP clients (Claude Code, Cursor)

claude mcp add --transport http cain https://cainstudio.online/mcp

More: Python SDK · TypeScript SDK · framework integrations · AI quickstart · decision signing key

Tested guarantees in this area

Every rule in these niches has its own page with its recorded result.

Evidence, receipts & proofs: 928 tested invariants — Signed records that prove what happened, checkable by anyone.
Autonomy, control loops & recovery: 407 tested invariants — Agents acting on their own, and how CAIN keeps them in bounds and recovers.

CAIN Drift — Warns you when an agent, model, tool or policy quietly changes.
CAIN Observability — A live window into what every agent is doing and why each action was allowed or stopped.
CAIN Plans — Checks an agent's plan before it starts, then holds it to that plan.
CAIN Resilience — Shows how CAIN keeps working when parts of it fail.
CAIN Sentinel — Always-on watchdog that detects trouble and contains it automatically.
CAIN Trajectory — Spots when an agent's chain of actions drifts somewhere it should not go, even in small steps.
Hubgate — One overview across all the MCPGate tools.
MCPWatch — Health and metrics for all your MCP servers in one place.

Full documentation

The complete reference, also at /docs/trace.

CAIN Trace Documentation#

Status: LIVE + FUNCTIONAL#

Verified 2026-09-08: /fabric/traces/ returns [] (empty - no traces created yet, but endpoint exists and is tenant-scoped).

CAIN Trace is fully functional. The core trace engine, API, dashboard, and correlation with CAIN decisions are implemented and working.

What is CAIN Trace?#

CAIN Trace records the complete execution lifecycle of every CAIN-protected action. It provides immutable, tenant-isolated execution history that correlates identity, decisions, enforcement, and evidence.

Core principle: Every CAIN decision creates a trace automatically. No manual trace creation required for normal operation.

Trace Lifecycle#

A trace progresses through these stages:

1. TRACE CREATED - Action received, trace initialized 2. IDENTITY RESOLVED - Principal authenticated (if identity_id provided) 3. POLICY EVALUATED - OPA policy checked 4. AUTHORIZATION EVALUATED - Agent permissions verified 5. RISK EVALUATED - Risk score calculated 6. TRAJECTORY EVALUATED - Trajectory safety checked (if applicable) 7. CAIN DECISION - Final verdict determined 8. ENFORCEMENT APPLIED - ALLOW or DENY enforced 9. EXECUTION - Tool/MCP call made (ALLOW only) 10. EVIDENCE CREATED - Immutable record stored 11. TRACE CLOSED - Final state recorded

Data Model#

ExecutionTrace#

Field	Type	Description
trace_id	string	Unique trace identifier (trc_xxxx)
tenant_id	string	Tenant namespace
agent_id	string	Agent that executed
identity_id	string	Identity of caller
action	string	Action performed
tool	string	Tool used
resource	string	Resource accessed
decision_id	string	CAIN decision ID
trajectory_id	string	Trajectory ID (if applicable)
evidence_id	string	Evidence record ID
verdict	enum	ALLOW, DENY, REQUIRE_APPROVAL, UNKNOWN, ERROR
status	enum	PENDING, COMPLETED, DENIED, FAILED, ERROR
execution_outcome	string	What happened
timestamp_start	datetime	When trace started
timestamp_end	datetime	When trace ended
duration_ms	float	Execution duration

TraceEvent#

Field	Type	Description
event_id	string	Unique event ID
trace_id	string	Parent trace
event_type	string	Type of event
stage	string	Lifecycle stage
verdict	string	Stage verdict
detail	dict	Event data
timestamp	datetime	When event occurred

API Endpoints#

Health Check#

GET /fabric/traces/health

Returns trace service health status.

Create Trace (Internal)#

Traces are created automatically by make_cain_decision(). Manual creation via:

POST /fabric/traces/?action=<action>&tool=<tool>

List Traces#

GET /fabric/traces/

Query parameters:

action - Filter by action
tool - Filter by tool
agent_id - Filter by agent
status - Filter by status
limit - Max results (default 100)

Get Trace#

GET /fabric/traces/{trace_id}

Returns full trace with events and integrity verification.

Get Trace Events#

GET /fabric/traces/{trace_id}/events

Returns ordered list of lifecycle events.

Get Trace Evidence#

GET /fabric/traces/{trace_id}/evidence

Returns evidence records with integrity verification.

Search Traces#

POST /fabric/traces/search

Advanced search with multiple filters.

Stats Summary#

GET /fabric/traces/stats/summary

Returns aggregate statistics.

Authentication#

All trace endpoints require:

X-Tenant-ID header - Tenant identifier
X-API-Key header - API key for authentication

Note: Traces are automatically created when make_cain_decision() is called. The tenant is derived from the API key.

Tenant Isolation#

Each tenant sees only their own traces
Cross-tenant access returns 404 (fail-closed)
No enumeration of other tenants' traces

Correlation#

Decision Correlation#

Every trace links to its CAIN decision via decision_id.

Evidence Correlation#

ALLOW decisions create evidence linked via evidence_id.

Trajectory Correlation#

When identity_id is provided, traces link to trajectories via trajectory_id.

Dashboard#

Access the trace dashboard at:

https://cainstudio.online/trace
https://cainstudio.online/trace/dashboard

The dashboard displays real traces from the backend with filtering and search capabilities.

CLI#

Trace commands are available via the CAIN CLI:

cain trace list
cain trace get <trace_id>
cain trace events <trace_id>

Trace States#

Status	Meaning
PENDING	Trace created, decision pending
COMPLETED	Action allowed and executed
DENIED	Action blocked by CAIN
FAILED	Execution failed
ERROR	System error (fail-closed)

Verdict Definitions#

Verdict	Meaning	Execution
ALLOW	Action permitted	Yes
DENY	Action blocked	No
REQUIRE_APPROVAL	Human approval needed	No
UNKNOWN	Cannot determine	No (fail-closed)
ERROR	System failure	No (fail-closed)

Real Examples#

ALLOW Trace#

{
  "trace_id": "trc_abc123",
  "tenant_id": "tenant-xyz",
  "action": "deploy_service",
  "tool": "kubectl",
  "verdict": "allow",
  "status": "completed",
  "decision_id": "cain:def456",
  "evidence_id": "ev_789",
  "execution_outcome": "Service deployed successfully"
}

DENY Trace#

{
  "trace_id": "trc_xyz789",
  "tenant_id": "tenant-xyz",
  "action": "delete_all_data",
  "tool": "database",
  "verdict": "deny",
  "status": "denied",
  "decision_id": "cain:ghi101",
  "execution_outcome": "Tool 'delete_all_data' is not registered for this agent"
}

Security Considerations#

Traces are immutable once finalized
Hash verification available via /evidence endpoint
Tenant isolation is enforced at the database level
All trace operations require authentication

Limitations#

Trace creation requires API key authentication
Dashboard requires correct tenant context
MCP tool tracing requires MCP integration

Try CAIN-42 on your own agents

Create a free account and every new account starts with a 7-day trial of the full platform. Or try the sandbox first, with no account at all.

Create a free account → · Try the sandbox · See the whole ecosystem