Coco
Look something up

Configuration

Look up the keys of coco.yaml, how .env is read, and the environment variables the SDK reads.

Look up the keys of coco.yaml, how .env is read, and the environment variables the SDK reads.

A project is a folder with a coco.yaml. The SDK finds the nearest one at or above the current folder, and the agent never sees it. coco init writes one with every key and a comment on each.


Example

project: payments-agent
mode: monitor              # monitor or enforce
ungoverned: impact         # impact, AUTO_EXECUTE or DENY
tell_agent: false
verdict_timeout: 2.0
limits:
  auto_release_limit: 10000
actions:
  send_payment: payments.send
contracts: contracts
policies: policies
ledger: .coco/ledger.db
classifier:
  url: ""
  api_key_env: COCO_CLASSIFIER_KEY
gate:
  url: ""
  key_env: COCO_API_KEY
pipeline:
  path: ""
policy:
  url: ""
  key_env: COCO_API_KEY
  model: ""

coco.yaml

KeyDefaultDescription
projectThe name given to coco initThe project's id. Against a gate where a key covers a whole account, the project's UUID, sent as X-Coco-Project. coco connect writes the UUID when the gate names one.
agentEmptyThe agent id on every receipt. Empty uses project. coco connect writes the name given to coco init here when it replaces project with the UUID.
modemonitormonitor: every call runs, and the receipt records what Enforce would do. enforce: DENY stops the call and ESCALATE waits for a person.
ungovernedimpactA tool no live contract governs. impact runs a tool that only reads, and escalates one that changes something or whose impact nobody establishes. AUTO_EXECUTE or DENY decide it outright.
tell_agentfalseIn Monitor, adds one line to a tool result saying what Enforce would do.
verdict_timeout2.0Seconds to wait for the classifier before a judge check takes its on_error verdict.
limits{}Numbers rules read as limits.*.
actions{}Tool name to contract action, where they differ.
contractscontractsThe contract folder.
policiespoliciesThe policy documents, for coco policy extract and upload.
ledger.coco/ledger.dbThe local ledger.
classifier.urlEmptycoco-classifier, for judge checks and the impact question. Empty runs rules only, and every judge check takes its on_error verdict.
classifier.api_key_envCOCO_CLASSIFIER_KEYThe variable holding the classifier's key.
gate.urlEmptyThe hosted gate. coco connect and coco init --key set it. Once set, the project decides through the gate and refuses to run without the key.
gate.key_envCOCO_API_KEYThe variable holding the project key.
pipeline.pathEmptyThe policy pipeline checkout, for coco policy extract.
policy.url, policy.key_envEmpty, COCO_API_KEYThe document service, for coco policy upload, models, jobs, pull, and retry. coco connect and coco init --key set the URL.
policy.modelEmptyThe model preset coco policy upload asks for when --model is absent. Empty takes the service's default.

Paths are relative to the folder holding coco.yaml, and ~ expands. A contract's own status lives in the contract file.

Good to know: With gate.url set and the key present, the gate holds the mode, ungoverned, limits, verdict_timeout, and contracts. The values in coco.yaml for those apply only when you decide in process. See What changes once connected.

.env

The coco command and the Claude Code hook read KEY=value lines from the project's .env. A variable already set in the shell wins.

In your own Python, load().engine() and load().guard() find the project key in .env on their own. For anything else in .env, such as COCO_MODEL, call load_env(".") first.

Keep in mind: coco connect writes the project key to .env with owner-only permissions. Add other variables to the file rather than copying .env.example over it.

Environment variables

VariableRead byDescription
COCO_API_KEYPython and TypeScript clients, cocoThe project key, coco_live_... or coco_test_....
COCO_GATE_URLPython and TypeScript clients, coco connect, coco initThe gate. Wins over gate.url. coco connect and coco init --key take --url, then this, then gate.url, then the hosted gate.
COCO_POLICY_URLcoco policy, coco connect, coco initThe document service. Wins over policy.url. coco connect and coco init --key take --policy-url, then this, then policy.url, then the hosted document service.
COCO_REVIEWER_TOKENcoco escalations, ledger, verify on the gateA reviewer's sign-in token.
COCO_CLASSIFIER_URLPython SDK, coco evalcoco-classifier. Wins over classifier.url.
COCO_CLASSIFIER_KEYPython SDKThe classifier's bearer key.
COCO_PIPELINEcoco policy extractThe pipeline checkout. Wins over pipeline.path.
DASHSCOPE_API_KEYThe pipelineModel Studio, for vision and rule extraction, in coco policy extract.
EMBEDDING_MODE, EMBEDDING_BASE_URL, EMBEDDING_API_KEYcoco policy extractAn embedding server for the pipeline's search index. Unset, the index uses offline hash embeddings.
COCO_MODEL, COCO_MODEL_BASE_URL, COCO_MODEL_API_KEYThe agent.py from coco initThe agent's own model, any endpoint speaking the chat completions format.
COCO_THREADThe agent.py from coco initThe thread id for coco run. Defaults to cli.
COCO_HOMEClaude Code hook and installerThe hook's project folder. Defaults to ~/.coco.
COCO_CLAUDE_DIRtrustcocoClaude Code's settings folder. Defaults to ~/.claude.
COCO_PYTHONtrustcocoA Python with trustcoco-sdk.
NO_COLORcocoPlain output.
HF_TOKEN, COCO_VAULT_DIRcoco eval vaultThe token to download the payment corpus, or the corpus on disk.
TAU3_BANKINGcoco eval tau3The tau3 banking domain on disk.
COCO_POLICY_CORPUScoco eval policyThe policy corpus.

On this page