Introduction
Getting Started with Coco
Welcome
Coco is a check that runs outside the agent and before the tool call. It reads three things, the behavioural contract you own, how far the case has got right now, and what this run already did, and it answers ALLOW, BLOCK or ESCALATE. No model takes part at decision time, so the same call against the same state always returns the same answer.
Every verdict writes one row, allows included, and that row is what an auditor reads. A call the gate never decided leaves no row, and the ledger names those gaps rather than hiding them.
The agent cannot skip the gate, talk its way past a verdict, or sign its own approval. What can remove the gate is an operator with the right file access, and what it does not stop says so before anything else does.
Two options
Coco governs an agent that already exists, so where the check sits depends on which runtime that agent lives in. There are two ways in and both are current.
| Option | The check is | Choose it when |
|---|---|---|
| npx | A PreToolUse hook on the machine | Your agent runs in Claude Code |
| SDK | One HTTP call from your harness | Your agent runs anywhere else |
Both run the same gate file, the same contracts and the same ledger. serve.py
does not reimplement a verdict, it runs gate/coco_gate.py as a subprocess with
the payload on stdin exactly as the hook does. A payload decided on a laptop can
be replayed against the service and produce the verdict it produced there, and
that is what makes the two sets of receipts comparable.
Architecture draws where the two converge and what each one adds.
npx @trustcoco/guardrails claude-code # the npx optiongate = CocoGate(GATE_URL, api_key=key, session_id=run_id)
verdict = gate.check("payment.send", {"amount": 25000}) # the SDK optionThe hosted gate is up now, and health needs no key.
curl -s https://gate.trustcoco.ai/demo/health{"status": "ok", "mode": "observe"}Start here
| Section | What it covers |
|---|---|
| Quick start | Pick a road, install it, watch it stop something, read the receipt |
| What is Coco | The architecture, the gate, contracts, the ledger, and what it does not stop |
| Installation | Both options in full, plus managed fleets, hosted and self-hosted |
| Using Coco | Modes, writing contracts, escalations, the ledger, the dashboard, the CLI |
| Questions | Enforcement, cost, and how it compares to what you already have |
Who this is for
Fraud, KYC and AML teams put agents into work whose rules are deterministic and already audited. The rules are deterministic and the agents are not. Coco validates an action against those rules before it executes and leaves evidence behind it.
Coco holds no funds and no keys. It does not sign, it does not settle, and it does not read what the model says. It decides whether an action runs.