Developer documentation
Quickstart
Last reviewed 31 August 2026
Quickstart
Five minutes from nothing to a protected agent. Nothing below is aspirational --
every command exists and every output block was captured from a real run.
Install
pip install cain-trust
No runtime dependencies. It will not touch your agent framework's dependency tree.
1. Authenticate
cain login
Paste your API key when prompted (it is not echoed), or pipe it:
echo "$MY_KEY" | cain login
The key is verified before it is stored, and stored at ~/.cain/credentials
with mode 0600 -- outside your project, so git add -A cannot commit it.
2. Create cain.yaml
cain init
Created cain.yaml Commit this file. It holds no secrets. agent demo-agent runtime langchain (detected) deployment hosted (CAIN Studio) policy default deny (fail-closed)
The runtime is detected from your requirements.txt / package.json. The
defaults are fail-closed: policy default deny, strict mode on.
3. Check the setup before you rely on it
cain doctor
doctor is willing to tell you bad news, which is the only thing that makes it
worth running. It reports shadow mode, stages that are marked enforcing but have
nothing loaded to enforce with, strict mode being off, and tools with no
restriction -- all of which look identical to "working" from the outside.
4. Protect the action
cain protect
That prints the smallest real change for your runtime. For Python:
from cain import trust
@trust(action="send_email", resource="customer_inbox")
def send_email(to, subject, body):
... # unchanged
Not authorized, not executed: the decorator raises NotAuthorized before the
body runs. Nothing else about your agent changes.
5. Run it
cain run agent.py
cain run exports the settings the SDK reads and executes your program. It does
not intercept syscalls -- protection comes from the SDK guarding the tool
calls inside your program. It refuses to start if the fabric is unreachable,
because with the fabric down every guarded call would be refused anyway.
6. See what happened
cain inspect # recent decisions cain explain <decision-id> # why one came out that way, stage by stage cain audit --decision <id> # the signature covering it
7. Prove it actually works
cain test
Runs the conformance suite and the red-team suite. It can fail, and on a fresh
deployment it usually does -- that is the point. See conformance.