Every tool call your agent makes — reading files, hitting APIs, running queries — is intercepted, policy-checked, and recorded in a cryptographically signed audit ledger. Before execution. Every time.
pip install custos-mcp
npm install custos-mcp
Custos is infrastructure, not a SaaS dashboard. Drop it in, define a policy, get audited.
Every tool call evaluated before execution against a YAML policy. Deny by default. First match wins. No runtime modification needed.
Ed25519-signed, SHA-256 hash-chained JSONL. Any modification to any record — including deletion or reordering — breaks the chain instantly.
Python signs. Node verifies. Or vice versa. The ledger format is a formal spec — enforced by a cross-language test on every commit.
gate.call("tool", args, fn) — no proxy subprocess, no JSON-RPC overhead. Wrap any function and get policy + audit in one line.
Drop custos proxy -- python -m server in front of any MCP server. No server code changes. All traffic passes through transparently.
Export a signed .tar.gz containing the full ledger, policy snapshot, and manifest. Verify it offline without running Custos.
Real-time allow/deny/error breakdown. Filter by tool or decision. Trace correlation across multi-agent pipelines. Runs in Python or Node.
Native DSL is zero-dep and ships everywhere. Cedar and OPA adapters available for teams with existing policy infrastructure. OTel spans optional.
YAML rules evaluated top-to-bottom. First match wins. Rich operators, dotted-path resolution, human-readable reasons recorded in every audit entry.
# deny everything by default
version: 1
id: production
default: deny
rules:
# block path traversal first
- id: no-traversal
when:
args.path: {contains: ".."}
decision: deny
reason: path traversal blocked
- id: workspace-reads
when:
tool: read_file
args.path: {prefix: "/workspace/"}
decision: allow
reason: workspace-only reads
- id: safe-http
when:
tool: http_request
args.method: {in: ["GET", "HEAD"]}
args.url: {regex: "^https://"}
decision: allow
- id: deny-shell
when:
tool: {regex: "^shell\\."}
decision: deny
reason: shell tools disabledConditions resolve against any field in the call context using dotted paths: tool, actor.id, args.*, server.id.
| Operator | Example |
|---|---|
| glob | "agent-*" |
| prefix | {prefix: "/workspace/"} |
| suffix | {suffix: ".json"} |
| contains | {contains: ".."} |
| regex | {regex: "^https://"} |
| in / not_in | {in: ["GET","HEAD"]} |
| gt / lt / gte / lte | {lte: 1048576} |
| exists | {exists: false} |
In-process SDK for embedding directly in agent code. No proxy required. Same API in Python and TypeScript.
from custos import (
Gate, Ledger, Actor, Server,
generate_keypair, load_policy
)
kp = generate_keypair()
kp.save(".custos")
ledger = Ledger(".custos/ledger.jsonl", kp)
policy = load_policy("policy.yaml")
gate = Gate(policy, ledger,
Actor("agent-1"),
Server("fs"))
r = gate.call(
"read_file",
{"path": "/workspace/data.csv"},
fn=read_file,
)
if r.allowed:
process(r.result)
else:
log(f"denied: {r.reason}")import {
Gate, Ledger,
generateKeypair, loadPolicy, newActor
} from "custos-mcp";
const kp = generateKeypair();
kp.save(".custos");
const ledger = new Ledger(
".custos/ledger.jsonl", kp);
const policy = loadPolicy("policy.yaml");
const gate = new Gate(
policy, ledger,
newActor("agent-1"), {id: "fs"});
const r = await gate.call(
"read_file",
{path: "/workspace/data.csv"},
({path}) => readFile(path),
);
if (r.allowed) process(r.result);
else log(`denied: ${r.reason}`);Wherever AI agents run in production, Custos provides the governance layer.
SOC 2, HIPAA, ISO 27001 all require audit trails. Export a signed evidence bundle and hand it to your auditor — no access to your systems required.
Each sub-agent gets its own policy and actor ID. Correlated trace IDs let you reconstruct exactly what happened across the entire pipeline.
A spike in denied shell.* calls or args.path contains ".." is a signal your agent is being prompted adversarially. Catch it in the ledger.
Run with a permissive policy during dev, collect the full ledger, review what tools your agent actually calls — then tighten before prod.
SaaS AI features? Each customer gets their own policy and ledger. Per-customer proof of what the agent accessed on their behalf.
Verify evidence bundles without running Custos. The ledger format is a public spec — implement a verifier in any language.
Open source. Apache 2.0. No vendor lock-in. Runs anywhere Python or Node runs.