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
| Key | Default | Description |
|---|---|---|
project | The name given to coco init | The 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. |
agent | Empty | The 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. |
mode | monitor | monitor: every call runs, and the receipt records what Enforce would do. enforce: DENY stops the call and ESCALATE waits for a person. |
ungoverned | impact | A 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_agent | false | In Monitor, adds one line to a tool result saying what Enforce would do. |
verdict_timeout | 2.0 | Seconds 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. |
contracts | contracts | The contract folder. |
policies | policies | The policy documents, for coco policy extract and upload. |
ledger | .coco/ledger.db | The local ledger. |
classifier.url | Empty | coco-classifier, for judge checks and the impact question. Empty runs rules only, and every judge check takes its on_error verdict. |
classifier.api_key_env | COCO_CLASSIFIER_KEY | The variable holding the classifier's key. |
gate.url | Empty | The 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_env | COCO_API_KEY | The variable holding the project key. |
pipeline.path | Empty | The policy pipeline checkout, for coco policy extract. |
policy.url, policy.key_env | Empty, COCO_API_KEY | The document service, for coco policy upload, models, jobs, pull, and retry. coco connect and coco init --key set the URL. |
policy.model | Empty | The 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
| Variable | Read by | Description |
|---|---|---|
COCO_API_KEY | Python and TypeScript clients, coco | The project key, coco_live_... or coco_test_.... |
COCO_GATE_URL | Python and TypeScript clients, coco connect, coco init | The gate. Wins over gate.url. coco connect and coco init --key take --url, then this, then gate.url, then the hosted gate. |
COCO_POLICY_URL | coco policy, coco connect, coco init | The 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_TOKEN | coco escalations, ledger, verify on the gate | A reviewer's sign-in token. |
COCO_CLASSIFIER_URL | Python SDK, coco eval | coco-classifier. Wins over classifier.url. |
COCO_CLASSIFIER_KEY | Python SDK | The classifier's bearer key. |
COCO_PIPELINE | coco policy extract | The pipeline checkout. Wins over pipeline.path. |
DASHSCOPE_API_KEY | The pipeline | Model Studio, for vision and rule extraction, in coco policy extract. |
EMBEDDING_MODE, EMBEDDING_BASE_URL, EMBEDDING_API_KEY | coco policy extract | An embedding server for the pipeline's search index. Unset, the index uses offline hash embeddings. |
COCO_MODEL, COCO_MODEL_BASE_URL, COCO_MODEL_API_KEY | The agent.py from coco init | The agent's own model, any endpoint speaking the chat completions format. |
COCO_THREAD | The agent.py from coco init | The thread id for coco run. Defaults to cli. |
COCO_HOME | Claude Code hook and installer | The hook's project folder. Defaults to ~/.coco. |
COCO_CLAUDE_DIR | trustcoco | Claude Code's settings folder. Defaults to ~/.claude. |
COCO_PYTHON | trustcoco | A Python with trustcoco-sdk. |
NO_COLOR | coco | Plain output. |
HF_TOKEN, COCO_VAULT_DIR | coco eval vault | The token to download the payment corpus, or the corpus on disk. |
TAU3_BANKING | coco eval tau3 | The tau3 banking domain on disk. |
COCO_POLICY_CORPUS | coco eval policy | The policy corpus. |